Zernio

Build me a personal social publishing API to replace Zernio. Requirements:

- Node + Fastify + better-sqlite3, single API key from .env, runs on my
  always-on box.
- Adapters ONLY for networks that hand out credentials on signup: Bluesky
  (app password via @atproto/api), Mastodon (access token), Telegram channel
  (bot token), Discord (webhook URL), Reddit (script app). One small adapter
  file per network so a sixth is addable later; scaffold nothing I don't use.
- POST /posts accepts text, image URLs, scheduledFor (ISO, my timezone), and
  a list of target accounts; media is downloaded once to media/ and checked
  for type and size before the post is accepted.
- A node-cron tick every minute publishes due posts: mark a row as sending
  before publishing so nothing ever double-posts, per-target status, 3
  retries with backoff, partial failures don't block other targets.
- GET /posts and GET /posts/:id return queue state and per-network
  permalinks; a plain localhost page lists the queue and recent failures.
- Optional webhook: POST to a URL from .env on published and failed.
- Binds to localhost only. No accounts, no telemetry.
- Out of scope: the approval-gated networks (Instagram, TikTok, LinkedIn,
  Threads, YouTube, Pinterest), DMs, comments, analytics, and ads. Skip
  anything that needs a phone number (WhatsApp, SMS, calls): numbers,
  carrier access, and KYC cannot be vibecoded.
- README: how to get each credential (Bluesky app password, Mastodon token,
  Telegram bot via BotFather, Reddit script app), plus an honest note that
  the closed networks need app review or paid API tiers.

# AGENTS.md — Build guide for Zernio

## Project scope
Expose a small REST API that accepts a post with media and a schedule time, queues it, and publishes to networks with open APIs (Bluesky, Mastodon, Telegram, Discord, Reddit) with retries and per-target status.

Catalogue verdict: no. The scheduler is the easy 10 percent and an agent can build it in a sitting. The other 90 percent is approval-gated: Instagram, TikTok, LinkedIn, Threads, YouTube, and Pinterest publishing all require a reviewed developer app (Meta App Review, TikTok audit, LinkedIn partner access), and X's API starts at $200/mo. Past the gate, the real product is upkeep: OAuth token refresh and revocation handling across 15 networks, per-platform media validation and transcoding, rate-limit cooldowns, and error remediation when platforms change behavior. Then there is the half that is not software at all: Zernio provisions real phone numbers across dozens of countries and runs WhatsApp Business, SMS, RCS, and voice calling on them, which means carrier relationships, per-country regulatory documents, and Meta business verification. No coding agent can conjure a phone number or pass KYC for you. Add the rest of the surface (unified DM/comment inbox, analytics, ads management across six ad platforms) and this is infra plus compliance, not a weekend of code.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- reviewed developer app per closed platform (Meta App Review, TikTok audit, LinkedIn partner program, Pinterest; X API paid tier)
- OAuth flows plus token storage, refresh, and revocation handling
- hosted scheduler, database, and job queue
- media storage with per-platform validation and transcoding
- webhook receivers for platform callbacks
- for messaging: WhatsApp Business API access, phone numbers with per-country KYC, and SMS/voice carrier contracts (or reselling Twilio, the kind of subscription you were replacing)

## Stack and architecture
- Node + Fastify + better-sqlite3, single API key from .env, runs on my always-on box.
- Model sources or channels, posts, dated observations, drafts, and reports; keep stable source IDs and timestamps.
- Interface for this social + messaging API workflow: a focused social + messaging API input, review, and export interface.

## Security and data integrity
- A node-cron tick every minute publishes due posts: mark a row as sending before publishing so nothing ever double-posts, per-target status, 3 retries with backoff, partial failures don't block other targets.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: publishing to approval-gated networks at all (Instagram, TikTok, LinkedIn, Threads, YouTube) without your own reviewed apps.

## Agent implementation rules
- Project rule, data: Model sources or channels, posts, dated observations, drafts, and reports; keep stable source IDs and timestamps.
- Project rule, behavior: Adapters ONLY for networks that hand out credentials on signup: Bluesky (app password via @atproto/api), Mastodon (access token), Telegram channel (bot token), Discord (webhook URL), Reddit (script app). One small adapter file per network so a sixth is addable later; scaffold nothing I don't use.
- Project rule, recovery: A node-cron tick every minute publishes due posts: mark a row as sending before publishing so nothing ever double-posts, per-target status, 3 retries with backoff, partial failures don't block other targets.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this social + messaging API operation with sample or user-owned data: Adapters ONLY for networks that hand out credentials on signup: Bluesky (app password via @atproto/api), Mastodon (access token), Telegram channel (bot token), Discord (webhook URL), Reddit (script app). One small adapter file per network so a sixth is addable later; scaffold nothing I don't use.
- Show a concrete result or export: POST /posts accepts text, image URLs, scheduledFor (ISO, my timezone), and a list of target accounts; media is downloaded once to media/ and checked for type and size before the post is accepted.
- State the practical limit: publishing to approval-gated networks at all (Instagram, TikTok, LinkedIn, Threads, YouTube) without your own reviewed apps.

## Engineering roadmap
1. Phase 1, architecture and data: Node + Fastify + better-sqlite3, single API key from .env, runs on my always-on box. Model sources or channels, posts, dated observations, drafts, and reports; keep stable source IDs and timestamps.
2. Phase 2, implement: Adapters ONLY for networks that hand out credentials on signup: Bluesky (app password via @atproto/api), Mastodon (access token), Telegram channel (bot token), Discord (webhook URL), Reddit (script app). One small adapter file per network so a sixth is addable later; scaffold nothing I don't use.
3. Phase 3, implement: A node-cron tick every minute publishes due posts: mark a row as sending before publishing so nothing ever double-posts, per-target status, 3 retries with backoff, partial failures don't block other targets.
4. Phase 4, review and output: GET /posts and GET /posts/:id return queue state and per-network permalinks; a plain localhost page lists the queue and recent failures. POST /posts accepts text, image URLs, scheduledFor (ISO, my timezone), and a list of target accounts; media is downloaded once to media/ and checked for type and size before the post is accepted.
5. Phase 5, recovery and acceptance: A node-cron tick every minute publishes due posts: mark a row as sending before publishing so nothing ever double-posts, per-target status, 3 retries with backoff, partial failures don't block other targets. Verify this invariant with a saved fixture: A failed platform call retains the draft and cannot be marked published; retries use a stable delivery key. State the practical limit: publishing to approval-gated networks at all (Instagram, TikTok, LinkedIn, Threads, YouTube) without your own reviewed apps.

## Paid-product capabilities outside this build
- publishing to approval-gated networks at all (Instagram, TikTok, LinkedIn, Threads, YouTube) without your own reviewed apps
- token lifecycle handling: refresh, revocation detection, reconnect flows across 15 networks
- platform error remediation, retry logic, and rate-limit cooldowns that keep queues alive
- the media pipeline: per-platform validation, compression, transcoding, re-hosting
- the entire messaging stack: phone numbers provisioned per country with KYC handled, WhatsApp Business templates and broadcasts, SMS, RCS, and voice calling
- everything else beyond posting: unified DM/comment/review inbox, contacts, analytics, ads APIs, conversion tracking

## Implementation prompt
Build me a personal social publishing API to replace Zernio. Requirements:

- Node + Fastify + better-sqlite3, single API key from .env, runs on my
  always-on box.
- Adapters ONLY for networks that hand out credentials on signup: Bluesky
  (app password via @atproto/api), Mastodon (access token), Telegram channel
  (bot token), Discord (webhook URL), Reddit (script app). One small adapter
  file per network so a sixth is addable later; scaffold nothing I don't use.
- POST /posts accepts text, image URLs, scheduledFor (ISO, my timezone), and
  a list of target accounts; media is downloaded once to media/ and checked
  for type and size before the post is accepted.
- A node-cron tick every minute publishes due posts: mark a row as sending
  before publishing so nothing ever double-posts, per-target status, 3
  retries with backoff, partial failures don't block other targets.
- GET /posts and GET /posts/:id return queue state and per-network
  permalinks; a plain localhost page lists the queue and recent failures.
- Optional webhook: POST to a URL from .env on published and failed.
- Binds to localhost only. No accounts, no telemetry.
- Out of scope: the approval-gated networks (Instagram, TikTok, LinkedIn,
  Threads, YouTube, Pinterest), DMs, comments, analytics, and ads. Skip
  anything that needs a phone number (WhatsApp, SMS, calls): numbers,
  carrier access, and KYC cannot be vibecoded.
- README: how to get each credential (Bluesky app password, Mastodon token,
  Telegram bot via BotFather, Reddit script app), plus an honest note that
  the closed networks need app review or paid API tiers.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.