IMPORTANT: Check Molecule-AI/internal repo for roadmap (PLAN.md), known issues, runbooks before starting work.

Daily public CHANGELOG. Fire at 23:50 UTC. Aggregates every merged PR
across the entire Molecule-AI/* org for the calendar day (00:00–23:50 UTC)
and publishes to the docs site as a customer-facing CHANGELOG entry.

You own the changelog. Marketing extracts highlights from it for blog posts
and socials, but the changelog itself is canonical and ships from your
PR — no marketing review needed.

## 1. ENUMERATE today's merged PRs across the org

```bash
TODAY=$(date -u +%Y-%m-%d)
mkdir -p /tmp/changelog-$TODAY
for repo in $(gh repo list Molecule-AI --limit 60 --json name --jq '.[].name'); do
  gh pr list --repo Molecule-AI/$repo --state merged \
    --search "merged:$TODAY" \
    --json number,title,mergedAt,author,labels,body \
    --limit 50 \
    > /tmp/changelog-$TODAY/$repo.json
done
```

## 2. CATEGORISE each PR into changelog sections

Read each PR's title + body + files-changed. Map to one of these sections:

| Section | Triggers |
|---|---|
| **🚀 New features** | `feat(...)` prefix, "feat:" in title, new endpoints/templates/plugins |
| **🐛 Bug fixes** | `fix(...)` prefix, "fix:" in title |
| **⚠️ Breaking changes** | "BREAKING" in title/body, removed endpoints, schema migrations that drop columns, API signature changes |
| **📦 Dependencies** | dependabot PRs, deps version bumps |
| **🔒 Security** | `security(...)` prefix, CVE patches, vulnerability fixes |
| **📚 Documentation** | `docs(...)` prefix — these are usually YOUR own PRs from the every-2h watch; include them so customers see docs progress |
| **🧹 Internal / housekeeping** | `chore(...)`, `refactor(...)`, CI changes, test-only changes — collapse into a single "X internal changes across N repos" line |

## 3. WRITE the changelog entry

Edit `content/docs/changelog.mdx` in the `Molecule-AI/docs` repo. Top-of-file
format (newest first):

```mdx
## 2026-04-16

### 🚀 New features
- **molecule-core**: Lark / Feishu channel adapter ([#480](https://github.com/Molecule-AI/molecule-core/pull/480))
- **molecule-core**: Provision-time env mutator hook for plugins ([#478](https://github.com/Molecule-AI/molecule-core/pull/478))
- **molecule-ai-org-template-molecule-dev**: Offensive Security Engineer role ([#1](...))

### 🐛 Bug fixes
- **molecule-ai-workspace-runtime**: Switch top-level `from adapters import` to absolute imports — unblocks every modular workspace template ([#2](...))
- **molecule-core**: PYTHONPATH=/app + `${WORKSPACE_DIR}` expansion for org imports ([#483](...))
- ...

### 📚 Documentation
- **docs**: Comprehensive content for all 15 pages ([#3](...))
- ...

### 🧹 Internal
- 41 gitignore-credentials PRs across plugin/template repos
- CI workflow fixes for macOS Keychain bypass on Fly publish

---
```

Hard rules:
- Newest day at top of file (prepend, don't append).
- One entry per PR in user-facing sections; collapse internal/CI/dependabot churn.
- For breaking changes: include a 1-line migration note inline with the entry, not buried elsewhere.
- For controlplane PRs: **do NOT include them**. Controlplane is a PRIVATE repo; mentioning specific changes leaks internals. The SaaS product changes go in via what's customer-visible (e.g. "tenant provisioning latency improved" is OK; "controlplane provisioner refactored to use X" is NOT).
- Include the date even on quiet days — "_No customer-visible changes today._" is a valid entry. Continuity > silence.

## 4. OPEN THE PR

Branch: `docs/changelog-YYYY-MM-DD`
Title: `docs(changelog): add YYYY-MM-DD entry`
Body:
```
Aggregated daily changelog for YYYY-MM-DD. Source: every merged PR across
Molecule-AI/* org for the calendar day. Generated by Documentation
Specialist's daily-changelog cron.

PR count by category:
- New features: N
- Bug fixes: N
- Breaking: N (if N > 0, list inline)
- Docs: N
- Internal: N

Marketing: if any of the New Features entries are launch-worthy, the
changelog now has the canonical wording — feel free to extract for blog
posts / socials.
```

## 5. NOTIFY MARKETING (only when there's something promotable)

If today's changelog has 1+ New Features, send Marketing Lead a short A2A:
```
delegate_task("Marketing Lead",
  f"Today's changelog landed at <docs-pr-url>. "
  f"Promotable items: {', '.join(highlights)}. "
  f"Extract for socials / blog if you want — no review needed on my end.")
```

For days with only fixes / internal changes, skip the notification.

## 6. MEMORY

```python
commit_memory(
  key=f"changelog-{TODAY}",
  value={
    "pr_count": N,
    "by_category": {...},
    "docs_pr_url": "<your changelog PR>",
    "marketing_notified": True/False,
  },
)
```

## 7. PRIVACY GATE — before you push

Final scan: grep your changelog draft for any of:
- File paths starting with `controlplane/`
- "Fly Machines", "tenant DB schema", any internal endpoint names
- Stripe webhook secrets, Anthropic API keys, anything else from `.env.example`

If any hit → DO NOT PUSH. Fix the offending entry first.

## DEFINITION OF DONE

- Branch + PR opened against `Molecule-AI/docs` with today's entry
- Memory `changelog-YYYY-MM-DD` written
- Marketing Lead notified if there were promotable items
- Quiet-day entry written if there was nothing else
