# Daily AI Digest Migration Runbook

Generated: 2026-06-12
Current source server: AIAgent-VPS, Ubuntu 24.04.3 LTS
Current app path: `/workspace/digest`
Current public URL: `https://www.tonki.dev/digest/`

This folder documents how the Daily AI Digest app works and how to move it to a new server.

## What This App Does

The app is a file-based PHP/static digest system plus a nightly Claude Code automation.

Runtime flow:

1. `systemd` starts `digest-orchestrator.timer` daily at 21:00 server time.
2. `digest-orchestrator.service` runs `/workspace/digest/run-digest-orchestrator.sh` as user `agent`.
3. The orchestrator verifies VPN/connectivity with `/workspace/digest/vpn-health.sh`.
4. The orchestrator launches Claude Code with:
   `claude --dangerously-skip-permissions --max-turns 200 -p "...generate the digest..."`
5. Claude reads `/workspace/digest/CLAUDE.md`.
6. Claude fetches Product Hunt via `DIGESTS/0-PRODUCTHUNT/fetch-producthunt.sh`.
7. Claude fetches Reddit through the `reddit-mcp-buddy` MCP server.
8. Claude writes `digest-archive/YYYY-MM-DD/checkpoint.md` continuously.
9. Claude writes `digest-archive/YYYY-MM-DD/index.php`.
10. Claude validates links with `validate-links.sh`.
11. Claude sends a Telegram message.
12. Claude appends the ISO date to `COMPLETED-DAYS.md`.
13. The orchestrator sees the fresh ledger entry, kills any remaining Claude process group, writes `.orchestrator-ack-YYYY-MM-DD`, and exits success.

The web side is served by Nginx with root `/workspace`. The digest URL maps directly to files under `/workspace/digest`.

## Files That Matter

- `CLAUDE.md`: main instructions for the Claude agent.
- `run-digest-orchestrator.sh`: retry, timeout, process killing, completion detection.
- `vpn-health.sh`: NordVPN/connectivity health check and repair.
- `DIGESTS/*/INTERESTS.md`: source-specific filtering preferences.
- `DIGESTS/*/MEMORY.md`: long-term memory and ongoing stories.
- `DIGESTS/*/SUBREDDITS.md`: Reddit source lists.
- `DIGESTS/0-PRODUCTHUNT/fetch-producthunt.sh`: Product Hunt GraphQL fetcher.
- `WEB/`: CSS, JS, assets, and template.
- `digest-archive/`: generated public digests.
- `COMPLETED-DAYS.md`: completion ledger used by the orchestrator.
- `.orchestrator-ack-YYYY-MM-DD`: daily success ack files.
- `logs/raw/`: raw run logs and Claude attempt logs.
- `logs/past-logs/`: structured run summaries.
- `systemd/`: repo copy of the VPN health units only. The real orchestrator units are installed in `/etc/systemd/system`.

## Current Server Components

Installed/currently observed:

- Ubuntu 24.04.3 LTS
- Nginx 1.24.0
- PHP 8.3 FPM, socket `/run/php/php8.3-fpm.sock`
- Node.js v20.19.6
- npm 11.17.0
- Claude Code 2.1.78 at `/home/agent/.local/bin/claude`
- jq 1.7
- curl 8.5.0
- git 2.43.0
- NordVPN 4.3.1, daemon `nordvpnd`
- UFW active, inbound allow: 22, 80, 443
- Certbot certificate for `tonki.dev` and `www.tonki.dev`
- Claude MCP server: `reddit-mcp-buddy` via `npx -y reddit-mcp-buddy`

## Critical Migration Warnings

Secrets are currently embedded in code/config:

- Product Hunt bearer token is hardcoded in `DIGESTS/0-PRODUCTHUNT/fetch-producthunt.sh`.
- Telegram bot token and chat id are hardcoded in `CLAUDE.md`.
- Claude auth lives outside the repo in `/home/agent/.claude/.credentials.json`.
- NordVPN auth/session lives outside the repo in NordVPN's local app state.

For a fast lift-and-shift, copy and re-authenticate these as described in `SECRETS.md`.
For a cleaner production setup, rotate the tokens and move them into environment variables.

## Known Current Issue

The feedback form in generated `index.php` writes to:

`/workspace/digest/SUGGESTIONS-FROM-USER.MD`

On the current server, `www-data` can read the digest PHP files but cannot write this suggestions file:

`www-data cannot write suggestions`

On the new server, fix this with one of:

```bash
sudo chgrp www-data /workspace/digest/SUGGESTIONS-FROM-USER.MD /workspace/digest
sudo chmod 664 /workspace/digest/SUGGESTIONS-FROM-USER.MD
sudo chmod 775 /workspace/digest
```

Or keep the file owned by `agent:www-data`:

```bash
sudo chown agent:www-data /workspace/digest/SUGGESTIONS-FROM-USER.MD
sudo chmod 664 /workspace/digest/SUGGESTIONS-FROM-USER.MD
```

## Read These In Order

1. `INSTALL.md`
2. `SERVER-CONFIG.md`
3. `SECRETS.md`
4. `OPERATIONS.md`
5. `VALIDATION.md`

