Skip to content

Social draft generation (status & ops) ​

Two VPS crons drive social posts:

ScheduleTimezoneDispatch scriptGitHub workflowMeta publish?
0 */12 * * *UTCscripts/dispatch-social-generate-render.mjssocial-generate-render.ymlNo — drafts await approval
0 19 * * *Europe/Londonscripts/dispatch-social-daily-post.mjssocial-video-publish.yml (Reel) or social-generate-render-publish.yml (carousel)Yes — one post a day

One post a day (#1378). Until 2026-11-03 the VPS posted three times a day (carousels at 16:00 and 20:00, a Reel at 19:00). The weekly learning run showed that volume was not growing reach (10 of 63 posts reached 10+ people, with about 20 followers), so it is now one post at 19:00 UK that alternates: even London days (days since 1970-01-01) a catalogue Reel, odd days a generated carousel. The day decides, so a failed or skipped day never shifts the pattern. node scripts/dispatch-social-daily-post.mjs --dry-run says which one today is.

Installers (after merge, on the scheduler VPS):

bash
cd /path/to/home-dashboard && git pull
sudo bash scripts/vps-install-social-generate-cron.sh
sudo bash scripts/vps-install-social-daily-post-cron.sh

The daily-post installer removes the old 16:00/20:00 image line (marker lovely-home-social-image-publish-cron) and any line that starts social-video-publish.yml or social-generate-render-publish.yml directly, then prints the crontab. The old 19:00 Reel line was added by hand, so check the printed crontab, and the other users' crontabs, for anything still posting.

See social-approval-gates.md for approval boundaries and env flags.

Render behaviour ​

  • When SOCIAL_POST_ID is set (both generate-render workflows), render-social-image.mjs renders only that draft — not the latest N drafts.
  • The cover photo is chosen with the post (see "Topic and photo rotation" below) and stored in social_posts.asset_id. If it fails to load, render tries the feature's other active photos in order and stores the one that worked. There is no Claude photo pick and no home-exterior stand-in any more (#1517).

Older one-off draft dispatch (social-generate-draft.yml / dispatch-social-generate-draft.mjs) remains manual workflow_dispatch only.

See github-actions-self-hosted-runner.md for runner install steps.

Cron line format ​

Each installer writes a comment marker on its own line, then the job.

Generate (drafts only):

cron
# lovely-home-social-generate-cron
0 */12 * * * CRON_TZ=UTC flock -n /var/lock/lovely-home/social-generate.lock bash -lc '...'

Daily post (Reel or carousel):

cron
# lovely-home-social-daily-post-cron
0 19 * * * CRON_TZ=Europe/London flock -n /var/lock/lovely-home/social-daily-post.lock bash -lc '...'

Lock files live under /var/lock/lovely-home/ (created by the installers, owned by the cron user). Do not use /var/run/... for flock: non-root cron users (e.g. ubuntu) cannot create lock files there and you will see flock: Permission denied.

/var/lock is a tmpfs, wiped at every reboot. The installers therefore write /etc/tmpfiles.d/lovely-home.conf (scripts/lib/vps-lock-dir.sh) so systemd recreates the folder at boot, and create it right away. On 2026-11-03 the VPS rebooted in the afternoon, the folder vanished, and the 19:00 daily post failed with flock: cannot open lock file ...: No such file or directory (#1396); re-running either installer once fixes it for good. If a cron log shows that error, that is the cause.

Do not put the marker in the middle of the schedule line. In /bin/sh, everything after # on that line is treated as a comment, so flock and the dispatch never run.

Logs:

  • Generate: /var/log/lovely-home/social-generate-cron.log
  • Daily post: /var/log/lovely-home/social-daily-post-cron.log

If a scheduled post does not appear, run VPS cron check (.github/workflows/vps-cron-check.yml, by hand, no inputs): it runs on the self-hosted runner on the VPS and prints both cron logs, the crontabs, the repo checkout the cron uses and the cron daemon's log around 19:00, so nobody has to SSH in for the logs.

Broken crontab (pre-fix installer) ​

If ubuntu’s crontab still looks like:

cron
0 */2 * * * CRON_TZ=UTC # lovely-home-social-generate-cron flock -n ...

fix it by moving the marker to the line above, or re-run the generate installer after merging the cron-line fix on main.

Immediate fix on the VPS (permission denied on /var/run) ​

If logs show flock: cannot open lock file /var/run/lovely-home-social-generate.lock: Permission denied:

  1. Quick: Edit the cron user’s crontab and change the flock path to /var/lock/lovely-home/social-generate.lock (create the directory first — step 2).
  2. Or prepare the directory and re-run the installer:
    bash
    sudo mkdir -p /var/lock/lovely-home
    sudo chown ubuntu:ubuntu /var/lock/lovely-home   # use gha:gha if cron runs as gha
    sudo REPO_DIR=/home/ubuntu/home-dashboard GHA_USER=ubuntu bash scripts/vps-install-social-generate-cron.sh

Claude settings (#984) ​

Every social Claude call (posts, image captions, insights) goes through social/claude-messages.mjs.

SettingValueWhy
max_tokens16,000 (DEFAULT_MAX_TOKENS)Current models think by default, and thinking counts toward max_tokens. At 2,048, a reply could stop while still thinking, so the job failed with "no text content (blocks: thinking; stop_reason: max_tokens)".
output_config.effortlow (ANTHROPIC_EFFORT env to change, none to omit)Short copy needs little reasoning, so this keeps thinking and cost small. Only sent to models that accept it; older models get no effort field.
Retryonce at 32,000If a reply is still cut off before any text, the helper retries once with more room and logs a warning. It fails only if the retry is thinking-only too.

The model is ANTHROPIC_MODEL (GitHub secret), defaulting to claude-sonnet-5.

Captions, hashtags and headings (#1252) ​

Each image post is written twice by Claude, then finished in code:

PartFacebookInstagram
Bodypost (longer)instagram_post (max 600 characters, first line at most 12 words, counting only words with a letter or digit so emoji and dashes are free (#1293), no URLs)
Linkthe post's link, tagged with utm_*"Link in bio → lovely-home.co.uk/links"
Hashtags2 from the bank5 from the bank
Imagemulti-photo post of the slidescarousel, alt_text on every slide
  • Hashtag bank: social/config/hashtags.json. Claude never writes hashtags (validation rejects them). social/lib/socialHashtags.mjs maps the post's audience to a group (hosts, sitters, pets, home) and picks #LovelyHome plus group tags, rotated by post id, so one post always gets the same set and consecutive posts differ. Edit the JSON to change tags; no code change needed.
  • Headings: Claude returns hook and two alternativeHooks. chooseHook in social/generate-post-lib.mjs scores them (under 8 words, a question or reader-facing opening, not "Lovely Home…", not "Did you know/Imagine", not opening like a recent post) and stores the best as hook, which is printed on the image.
  • Reels: each entry in social/videos/catalog.json has an audience. Captions there hold the story only; buildVideoCaption adds a tagged homepage link (Facebook) or link in bio (Instagram) and bank hashtags.
  • Reel files: each catalogue file must be uploaded to the lovely-home-social-media bucket as social-videos/{file} before the rotation can post it. social/publish-social-video.mjs checks every catalogue file on media.lovely-home.co.uk first; a missing one is skipped with a warning on the run page and in the job summary, and the rotation posts the next video. Asking for a missing video by number fails. On 2026-10-31 the rotation reached video 15 (15-Donna-wifi.mp4) before it was uploaded, and the run stopped there.
  • Reel intros (#1381): every catalogue Reel used to open with a 1.5 to 1.7 s Lovely Home logo animation, and viewers left during it. Social — cut Reel intros (.github/workflows/social-trim-video-intros.yml, run by hand on the self-hosted runner, needs ffmpeg on the VPS) runs social/trim-video-intros.mjs: for each file in social/videos/intro-cuts.json it downloads the Reel from media.lovely-home.co.uk, keeps the untouched original at social-videos/originals/{file} (once), drops the first N seconds with ffmpeg (the cut sits before the first spoken word; four files cut at 1.45 to 1.6 s for that reason) and uploads over social-videos/{file}. The outro and voice-over stay. Running it twice trims twice, so a new Reel that still has an intro gets an entry in intro-cuts.json and one run with its name in the files input; a Reel made without an intro (17 onwards) needs no entry. The bucket is served without caching, so the new file is live at once. Done on all 16 on 2026-11-03.
  • GitHub artifacts: the image post workflows keep no artifact copy of the slides; R2 holds them (social/{post_id}-{n}.jpg). The account's artifact storage is 500 MB on the free plan, and when it was full on 2026-10-31 the posts went out but the runs went red. Asset library previews are kept 1 day.
  • Links: the allow-list in social/marketing-urls.mjs includes the audience pages (/for-holiday-lets, /for-house-shares, /for-live-in-carers), /how-it-works and the two welcome book checklist guides.
  • Rows written before #1252 have no instagram_post; Instagram uses post for them.
  • Suggested visual: since #1517 the cover photo is chosen in code from the feature's photo list, and suggestedVisual is Claude's one-sentence description of that photo, used as the cover alt text. It is not checked against subjects named in the copy any more (#1597): the old check from #1299 dated from when Claude picked the photo, and on 2026-11-14 it failed a cleaner checklist post three times because the copy mentioned "the bins due".
  • Retry feedback: a retry gets the failed draft back with its error and is asked to return that draft with only the failing part changed, plus the earlier errors to keep passing (#1599). Before that, each retry wrote a brand-new post and often broke a different rule. Errors quote what was wrong (the slide title and its word count, the Instagram first line, the titles of slides 2 and 3) so the next draft knows what to change (#1293, #1597).

Topic and photo rotation (#1517) ​

Until 2026-11-09 Claude chose each carousel's topic itself. It kept going back to bins and Wi-Fi, and the only check on repeats was the last 12 rows of social_posts, most of them 12-hourly drafts that were never posted. Reels weren't counted, and the photo had no memory, so the same bin photo came back. The tips were generic "write it down" advice, because the prompt let only one tip mention Lovely Home and brand.md didn't list most features.

Now every carousel sells one feature, picked in code:

  • The list: social/config/features.json. Each feature has its plan (free = every plan, plus = Lovely Home+ and Multi Home), the everyday problem, the facts we may say (with their sources), the audiences, its photos (asset ids) and a link. tests/socialFeatures.test.js checks the Plus features against planFeatures in functions/api/platform/platformPlanTier.js, checks the Free limits against the limits in code, and checks that every photo exists in the asset manifest. To promote something new, add it here first, with its source.
  • Pick: social/generate-post.mjs reads published carousels (social_posts.feature_id) and Reels (social_videos and social_video_publications, mapped through feature in social/videos/catalog.json). pickFeature in social/lib/socialFeatures.mjs drops anything in the newest 8 published posts, then takes the feature used longest ago (ties at random). A feature with no active photo can't be picked.
  • Photo: rankFeatureAssets picks the feature's active photo used longest ago, stored in social_posts.asset_id (migration 0024). Its manifest prompt tells Claude what the photo shows.
  • Copy: Claude gets the feature's facts as the only product facts it may use. Slide 1 is the problem, and slides 2 and 3 are how Lovely Home solves it. validateFeatureCopy requires Lovely Home to be named on slide 2 or 3, and "Lovely Home+" in the post, the Instagram caption and the slides for a Plus feature.
  • Recent posts shown to Claude (for wording only) are the newest published ones. Unpublished drafts no longer count.

Image posts are 4:5 (1080×1350) carousels, built from the post in this order:

SlideContent
1, coverthe chosen photo full-bleed, audience label, the chosen hook, "Swipe to see how"
2, problem"The problem" label, then slide 1 from slides: title (at most 8 words), body (at most 120 characters)
3 and 4, howthe feature and plan as the label (for example "Bin reminders · Lovely Home+"), then slides 2 and 3
lastthe feature and plan (endTitle, for example "Bin reminders come with Lovely Home+"), with "Start on the Free plan and upgrade when you need it." for Plus or "No app to download. Everyone just opens a link." for every-plan features
  • Claude returns exactly 3 slides in slides, stored as JSON in social_posts.slides (migration 0019). parseSlides in social/lib/socialSlides.mjs validates them (no hashtags or URLs), and the slides count towards the claims check and, when the heading names no subject, the suggested-visual check.
  • Render: social/render-social-image.mjs uses the HTML in social/lib/socialSlideHtml.mjs and writes social/output/social-image-<post id>-{n}.jpg. It only picks up drafts with slides and a feature.
  • Upload: social/upload-social-slides.mjs puts each slide in R2 at social/<post id>-{n}.jpg and checks the public URL. All three render workflows use it.
  • Publish: social/publish-social-image.mjs posts the slides to Facebook as unpublished photos attached to one feed post, and to Instagram as carousel children (each with alt_text) under one CAROUSEL container.
  • Drafts written before #1517 have no feature (and 2-tip drafts fail the 3-slide check), so they no longer render or publish; generate a new post instead.

Weekly learning loop (#1282) ​

Every Monday at 06:40 UTC, Social — weekly learning (.github/workflows/social-learning.yml, self-hosted runner) runs social/run-social-learning.mjs:

  1. It takes posts and Reels published 28 to 2 days ago. Newer ones are still gaining reach, so they wait a week. For each one it reads the newest social_insights snapshot, which holds lifetime totals.
  2. social/lib/socialLearning.mjs scores each item per platform as interactions per person reached: likes, comments and shares, plus saves on Instagram or clicks on Facebook (social_insights.clicks, migration 0020), divided by reach. Items with reach under 10 are left out.
  3. It compares formats (carousel, single image, Reel), audiences and content pillars by their median rate. A group needs 3 or more posts on a platform. A group is stronger at 1.25 times the platform median or above, and weaker at 0.75 times or below. A group that is strong on one platform and weak on the other counts as neither.
  4. It stores the summary and the guidance in social_learnings and writes tables to the job page.

The post writer (social/generate-post.mjs) reads the newest social_learnings row. buildLearningPromptLines adds a "What worked recently" section to Claude's instruction. It asks Claude to lean towards the stronger audiences and pillars on about half of posts and keep rotating on the rest, and to try a new angle for the weaker ones instead of dropping them. It also shows the best headings as shapes to match (never to copy) and the worst as shapes to avoid. With no row yet, or too little data, the section is left out.

To refresh the guidance outside Monday, run the workflow by hand.

Followers (#1288) ​

Each insights run (social/collect-social-insights.mjs, every 3 hours) also stores account size in social_account_stats (migration 0021), one row per platform per London day: Instagram followers_count, Facebook Page followers_count, and Instagram profile_views for the previous full day. It does this after the post snapshots are saved, and fails loudly if Meta leaves a value out. The weekly report adds a Followers table: followers now, change over 7 and 28 days, and Instagram profile visits in the last 7 days. It is also stored in summary_json.accountStats. The change columns read "not enough days yet" until there are 7 or 28 days of rows.

Daily engagement list (#1284) ​

Small accounts grow by following and commenting in their niche, which a person has to do: Meta has no API for following, and tools that log in as us break its terms. Social — daily engagement list (.github/workflows/social-engagement-list.yml, 07:30 UTC daily, self-hosted runner) does the finding:

  1. social/run-social-engagement-list.mjs searches each hashtag in social/config/engagement.json with ig_hashtag_search, then reads up to 25 posts from /{hashtag-id}/recent_media (the last 24 hours). Busy hashtags such as #housesitting make Meta answer error 1, "Please reduce the amount of data", even at 25, so on error 1 the job asks again for 10, then 5, and fails only if 5 is refused too (#1286). Meta allows 30 unique hashtags per 7 days, so the config is capped at 30.
  2. Each caption is cut to 300 characters for the prompt (160 in the email) with shortenText (social/lib/shortenText.mjs), which cuts on whole characters. A plain slice can split an emoji in half, and the Anthropic API rejects the request as invalid JSON ("unexpected end of hex escape", #1487). Claude picks up to postsPerEmail posts by real hosts, sitters and homeowners, skipping ads, giveaways, agencies, competitors and anything sensitive. It drafts a comment of 25 words or fewer for each. parsePicks in social/lib/socialEngagementList.mjs drops a pick whose comment has a link or hashtag, or mentions Lovely Home.
  3. One email goes via Resend to the recipients in the config: a Reddit section of subreddit links (#1379), an Instagram section (steps, then each post with its link and suggested comment) and a TikTok section (#1301). Nothing is posted anywhere.

Reddit questions to answer (#1379) ​

With about 20 followers, our own posts can't reach many people, so the best lever is answering questions where hosts and sitters already are. The Reddit section comes first in the email: steps, then one link per subreddit in subreddits to its newest posts (https://www.reddit.com/r/{name}/new/). The person opens two, picks questions from hosts or sitters with few replies, and answers two from their own Reddit account, as a host. Lovely Home is only mentioned when someone asks for a tool, with a plain "I built it".

The job does not read Reddit, so there are no picked questions or drafted answers. Reddit stopped taking new public API access requests on 2026-10-31, has answered HTTP 403 to listing reads that are not signed in since mid October 2026 (the first branch run on 2026-11-03 hit this), and closes its public Data API in March 2027; its Developer Platform is for apps that run inside Reddit. A Reddit account for the person, not for the job, is what works.

TikTok has no free API that searches other people's videos: its Research API is only for academic researchers. So the TikTok section is steps plus one link per tag in tiktokHashtags (up to 10) to https://www.tiktok.com/tag/{tag}, and the person picks the videos. On a day with no Instagram picks the email still goes out with the TikTok section; Claude is not called when there are no Instagram candidates.

The email runs every day, weekends included (Mark, 2026-10-31). Scheduled GitHub runs can start hours late or be skipped when GitHub is busy; if the email hasn't arrived, run the workflow by hand.

Edit social/config/engagement.json to change recipients, Instagram or TikTok hashtags, subreddits, or the number of posts. Hashtag search needs the Instagram Public Content Access feature on the Meta app. Without it the job fails and names that feature.

Threads (#1289) ​

Each carousel post also goes to Threads, after Facebook and Instagram, from the same slide images. social/publish-social-image.mjs creates one Threads image container per slide (with its alt text), a CAROUSEL container, waits for each to reach FINISHED, publishes, and stores social_posts.threads_media_id (migration 0022). A post becomes published only after Threads. After Threads the post is threads_published until TikTok is done (see below). If Threads fails, the post stays instagram_published with publish_error set, and a re-run posts to Threads only. Threads can say a container is FINISHED a moment before threads_publish can see it, and then answers "Media Not Found" (code 24, subcode 4279009); publishThreadsContainer retries that answer every 10 seconds, up to 4 times (#1322). A container publishes at most once, so a retry cannot post twice.

The text (buildThreadsText in social/lib/socialCaption.mjs) is the Instagram copy, the CTA, the website link tagged utm_source=threads (links are clickable on Threads), and one audience topic tag from the hashtag bank, since Threads allows one tag per post. Threads caps posts at 500 characters, so long copy is cut back to its last whole sentence that fits.

Token. Threads uses its own user token (graph.threads.net), not the Meta system user token. It lasts 60 days, and each renewal returns a new token, so it is stored in D1 (social_platform_tokens) rather than a GitHub secret. Social — Threads token (.github/workflows/social-threads-token.yml, Sundays 05:10 UTC) runs social/run-threads-token.mjs. The first run stores the THREADS_ACCESS_TOKEN secret as it is: the User Token Generator already gives a 60-day token, which Threads refuses to exchange again (#1291), so the run reads its real expiry from debug_token. Later runs renew the stored token (Threads only renews a token that is at least a day old). Publishing loads the token before posting anywhere and stops if it is missing or expired.

One-time setup (or after a token has expired):

  1. In the Meta app, add the "Access the Threads API" use case with threads_basic and threads_content_publish, and add the Lovely Home Threads profile as a Threads Tester (accept the invite in the Threads app under Settings → Account → Website permissions).
  2. Use cases → Access the Threads API → Settings: generate a token for the profile with the User Token Generator.
  3. Save it as the repo secret THREADS_ACCESS_TOKEN. If a token is already stored, delete the threads row from social_platform_tokens first. Then run Social — Threads token.

Reels are not posted to Threads yet, and Threads views and replies are not collected yet.

TikTok (#1295) ​

Posts go to the Lovely Home TikTok account's inbox as drafts; someone opens TikTok, taps the inbox notification and posts. TikTok's Direct Post only posts privately (SELF_ONLY) until TikTok audits the app, and the audit wants a per-post consent screen, so inbox upload (video.upload scope) is what works today. Mark chose this on 2026-10-30, with an audit application to follow.

  • Carousels: after Threads, social/publish-social-image.mjs sends the slides as one TikTok photo post (/v2/post/publish/content/init/, post_mode: MEDIA_UPLOAD) with the heading as the title (cut to whole words within 90 characters) and the Instagram-style caption (buildSocialCaption(row, 'tiktok'): short copy, CTA, link in bio, 5 bank hashtags) as the description. TikTok photo posts take JPEG or WebP only, so slides render as JPEG (social-image-<post id>-{n}.jpg, quality 92) for every platform.
  • Reels: after Instagram, social/publish-social-video.mjs sends the catalogue video (/v2/post/publish/inbox/video/init/). That endpoint has no caption field, so Reel drafts arrive empty (TikTok may fill in a tag of its own). Once the draft reaches the inbox, the run emails the TikTok caption (story, link in bio, 5 bank hashtags) to the recipients in social/config/engagement.json through Resend, with the steps to paste it in (#1524; social/lib/tiktokCaptionEmail.mjs). That is one email every other day. The caption is also in the job summary. If the email fails, the run goes red after the draft is sent; a re-run does not send the draft or the email again, so copy the caption from the job summary. Reels can only carry a caption once the app is approved for Direct Post.
  • Both use PULL_FROM_URL, so media.lovely-home.co.uk must be a verified domain in the TikTok app. Each run waits until TikTok reports SEND_TO_USER_INBOX and stores tiktok_publish_id on social_posts / social_videos (migration 0023; rotated videos archive it in social_video_publications). Videos are instagram_published until the TikTok step is done, posts threads_published; a re-run after a TikTok failure only retries TikTok.
  • Until TikTok is connected (no tiktok row in social_platform_tokens) both scripts log "TikTok is not connected yet" and skip it. Once connected, an expired token stops the publish before anything is posted.

Token. TikTok access tokens last 24 hours and refresh tokens 365 days; each renewal returns a new refresh token, so both live in social_platform_tokens. Social — TikTok token (.github/workflows/social-tiktok-token.yml, 03:20 and 13:20 UTC) runs social/run-tiktok-token.mjs to renew it. Scheduled runs do nothing until the TikTok client key and secret are set.

One-time setup (or if the refresh token runs out):

  1. At developers.tiktok.com, sign in with the Lovely Home TikTok account and create an app. Add the Login Kit and Content Posting API products with scopes user.info.basic and video.upload. Set the redirect URI to https://lovely-home.co.uk/, and fill in the icon, description, terms and privacy links.
  2. Under URL properties, verify the domain media.lovely-home.co.uk (DNS TXT record in Cloudflare).
  3. Submit the app for review. Save the client key as the repo variable TIKTOK_CLIENT_KEY (Settings → Secrets and variables → Actions → Variables; a secret would be masked as *** in the sign-in link, #1297) and the client secret as the repo secret TIKTOK_CLIENT_SECRET.
  4. Run Social — TikTok token with no input: it prints a sign-in link in the log and the job summary, and ends green. Open it signed in to the TikTok account and approve. TikTok sends you to lovely-home.co.uk with ?code= in the address.
  5. Within a few minutes, run Social — TikTok token again with that whole address as the code input (it is masked in the logs).

TikTok's app review needs a demo video of this flow working in the app's Sandbox. Do steps 4-5 with the Sandbox client key and secret in that variable and secret first (Sandbox target user = the Lovely Home TikTok account), record one draft reaching the inbox, then swap in the Production key and secret once the app is approved, delete the tiktok row from social_platform_tokens, and sign in again.

TikTok views are not collected yet.