# Lectern

> Sovereign Farcaster client for macOS. Custody, recovery, and signer keys live in macOS Keychain. EIP-1559 transactions signed locally with secp256k1. No analytics, no telemetry, no servers in the middle. Pro subscription is 6.9 USDC/mo (or 79 USDC/yr) paid on-chain — no app-store cut, no card on file. Lectern Pro unlocks per-machine: once any account on the Mac pays, every account on that Mac is Pro until the paid-through date.

## Product

- [Homepage](/): hero, three feature cards, protocol primitives list.
- [User Guide](/docs/user-guide): canonical long-form guide. Every CLI command, every Settings panel, the first-launch tutorial, Pro feature inventory, troubleshooting. **Recommended for AI agents asking "how do I X in Lectern".**
- [Pricing](/pricing): free vs. Pro feature lists, payment + trial details.
- [Support](/support): help, contact, status.
- [Legal](/legal): privacy policy, terms of service.

## v0.2.0 ship plan

**Target: 2026-07-22.** First public macOS release. The `lectern` CLI tool has been dogfood-stable for months; the macOS app ships at v0.2.0 alongside the $KEYNOTE token's Day 1 utility wiring. Public download surfaces are not yet wired — pre-launch builds are operator-distributed via private URLs.

## First-launch experience

A 6-step **Welcome Tutorial** modal fires the first time a free-tier user reaches the main shell. Steps: (1) persona pick — "I use farcaster.xyz" or "I'm new to Farcaster"; (2) sidebar tour; (3) persona-specific quality-of-life deltas; (4) hands-on first-cast hints; (5) Pro feature preview with one-click upgrade button that opens the wallet panel pre-filled with the 6.9 USDC USDC.b send to the canonical Pro receiver on Base; (6) help links. Re-openable any time from the macOS menu bar: **Help → Welcome Tutorial (⌘?)**.

Quote-cast surfaces: reaction-bar `quote.bubble` icon button + right-click "Quote cast" context-menu item on every cast row. Both open the composer with the cast's canonical farcaster.xyz URL pre-embedded; the embed classifier routes that URL into a quote-cast box on the new cast.

## Free tier (forever)

- Full feed (chronological / view-as / own casts), composer, replies, threads.
- Long casts up to 1024 bytes; auto-splits into numbered threads past that.
- Farcaster DCs + XMTP DCs share one inbox; live streaming with auto-reconnect.
- Mini App SDK runtime — wallet send, sendToken, EIP-5792 batched calls (stubs land in v1; real broadcasts in v1.1).
- Hub-indexed mini-app discovery, refreshed daily via the lctrn.app trending indexer. The indexer extracts `frame.homeUrl` from each app's `/.well-known/farcaster.json` manifest so Open/Add buttons route to the actual mini-app entry URL, not the bare host origin.
- Multi-account up to 2 slots, bookmarks (local-only JSON), per-category notifications, 2FA (TouchID + optional TOTP).
- Sovereign keys in macOS Keychain (v2 permissive ACL — readable by both the GUI and the launchd-spawned background CLI without prompting).
- System notifications with **subscribedSince floor** per FID — only events after first bind fire as banners. New-install users don't get a flood of retroactive notifications. Manual "clear all" button in the notifications modal wipes both in-app and macOS Notification Center.
- Casts carry a 27-byte attribution stamp ("Sent via Lectern on macOS").

## Pro tier (6.9 USDC/mo, 79 USDC/yr, 7-day free trial)

- **Snap Maker** — 14 templates (profile card, linktree, announce, event, tip jar, quote, poll, AMA, claim, verify, mini-app-launch, tip, leaderboard, RSVP) with live preview. 8 are full-stack (devflair worker renders OG + JSON manifest); 6 are Swift-preview-only (fall back to `card` kind at upload). The `mini-app-launch` template is the only one that renders natively in Warpcast via embedded `fc:miniapp` meta tag.
- **Cast Analytics** — engagement timeline, time-of-day heatmap, cadence report, top-cast leaderboard, on-device AI growth plan via Apple Intelligence. Per-FID JSON cache. User-picked scan size (50 / 100 / 200 / 500 / 1000 casts) with live ETA + cancel; scans survive modal close.
- **Airdrop Pro Tool** — 5-step wizard (From / Token / Cohort / Amount / Review). Routes through the canonical Disperse contract (`0xD152F549545093347A162Dce210e7293F1452150`, immutable + ownerless + zero protocol fee) on Base / OP / Arbitrum / Ethereum. Auto-chunks above 500 recipients. FID → verifications[0] → custody-address resolution. Lectern fee: `$1 USDC + 25 bps capped at $25`, free under 10 recipients.
- **Follow Manager** — bulk review non-mutuals + inactive accounts, batch unfollow.
- **BoostModal engage-on-boost** ($KEYNOTE feature, opt-in) — boosting a cast with KEYNOTE can also queue Like / Recast / Quote-cast writes from your own Farcaster signer that fire 5min–6hr later (random jitter) via the EngagementScheduler. Per-week per-booster caps (≤3 quotes, ≤5 recasts) stay below classifier thresholds.
- **✨ Apple Intelligence helpers** — reply ideas, thread TL;DR, tone tweak. Runs on Apple's on-device Foundation Models. Requires macOS 26+ on Apple silicon; never leaves the Mac.
- **Local cast archive** — append-only JSONL of every cast you publish, written to `~/Library/Application Support/Lectern/archive/<account>.jsonl`. Hub backfill via one-shot `castsByFid` walk + dedup. Export as Markdown or raw JSONL. **Stays accessible even if Pro lapses** — never hold the user's own writing history hostage.
- **Theme customization** with import / export.
- **Unlimited account slots** (free is capped at 2 active accounts; hidden accounts don't count against the cap).
- **Operator console** — `lectern` CLI with declarative `plan` / `apply` / `import` / `export` (Terraform-style exit codes: 0 no-op, 2 changes pending, 1 error).
- **No cast stamp on broadcast.**
- Long-cast TEN_K_CAST + profile-banner upload work in Lectern when the FID also holds **Farcaster Pro** (Hub-gated, separate from Lectern Pro).

## Machine-global Pro across accounts

Once **any account on the Mac** pays for Pro, **every account on the Mac** is treated as Pro. The macOS-global `License.machinePaidThrough` mirrors `max(record.paidThrough)` across loaded accounts. Pay once with your personal account, switch to dev/bot/second-fid accounts with `⌘1`–`⌘9` — sidebar locks stay open, Snap Maker stays unlocked, the cast stamp stays off. Pro auto-expires when the latest paid-through date passes. The per-FID `SubscriptionRecord.paidThrough` is still tracked independently for receipts + refund attribution.

## Payment + one-click upgrade

Three in-app surfaces all open the wallet panel pre-filled with the Pro USDC send (chain Base 8453, USDC.b contract, receiver `0x14060A0838d2351799AbF3e92C4D148B091373ce`, amount 6.9, sender = user's picked EVM wallet):

- **Settings → License → "Come back to Pro"** (shown when the user previously accepted free tier after a lapse)
- **LapseChoiceModal "Top up Pro →"** (fires once on Pro → lapsed transition)
- **GiftedLicenseReminderBanner "Upgrade →"** (shown when a launch-code grant is nearing expiry)

The user still hits "send" in the wallet panel — Lectern never auto-broadcasts. **Wallet sends are biometric-gated** (TouchID/passcode); the `wallet-send` AuthPolicy entry was added 2026-06-04 after the first paid Pro subscription test surfaced a missing gate.

$KEYNOTE staking discount: stake 25M / 50M / 100M for 15% / 25% / 40% off. Or pay in KEYNOTE at a 5% premium (demoted path).

Lapse behavior (softened 2026-05-29): D0–D1 red banner, D2 yellow snoozable banner, D3+ Settings-only reminder. **Writes are never blocked, app never refuses to launch.** Only the cast stamp returns. Pick "continue as free" from the lapse modal to silence the banner permanently. Key-export path always available.

## Background scheduler (SMAppService)

- Scheduled casts (composed in the macOS app or via the `lectern scheduled` CLI) fire only while Lectern.app is open by default. The in-app runner ticks every 60s.
- To fire scheduled casts when Lectern is closed: **Settings → Developer → Background Scheduler → Install**. This registers a launchd agent via Apple's `SMAppService` API. The agent's plist is bundled inside `Lectern.app/Contents/Library/LaunchAgents/studio.shyguy.lectern.scheduler.plist` and references the bundled CLI at `Contents/Helpers/lectern` via the manifest's `BundleProgram` key (with conventional `argv[0] = "lectern"` so ArgumentParser parses correctly).
- The user-visible "running in background" notification + Login Items entry are attributed to the app bundle ("Lectern"), not the developer-cert CN — because SMAppService manages the agent through the app's Info.plist, not via `launchctl bootstrap`.
- First install may prompt for admin password once — that's the legacy v1 → v2 Keychain ACL migration for older signer keys. After the migration, the background CLI reads signers silently. The interactive variant fires at install (operator is at the keyboard); silent variants run at app launch + at schedule time and refuse to surprise the user with prompts.
- CLI fallback (for `swift run lectern-app` dev mode + headless setups): `lectern scheduled install` / `lectern scheduled uninstall`.

## System notifications

- Two surfaces: in-app inbox (bell icon, `⌘⇧N`) + macOS Notification Center (Settings → Notifications toggle).
- Polled via Hub `/v1/events` at 5s + Farcaster DC inbox at 30s. Sub-10s end-to-end latency for cast → macOS notification.
- All polling timers run on `RunLoop.main` common-mode so they continue ticking during UI event tracking (scrolling, menus, drag). Default `Timer.scheduledTimer` pauses during event tracking — Lectern explicitly avoids that so notifications don't go stale while you're using the app.
- **subscribedSince floor** — per-FID Farcaster-epoch timestamp persisted in UserDefaults at first bind. Events older than the floor are silently dropped even if the cursor catches them up. Stops the "retroactive flood on fresh install" symptom.
- **Manual "clear all"** button in NotificationsModal — empties in-app items, bumps the lastSeenTimestamp, and calls `UNUserNotificationCenter.removeAllDeliveredNotifications()` + `.removeAllPendingNotificationRequests()`. User-driven escape valve.

## Wallet panel

- Three tabs: **Receive** (180×180 QR + click-to-copy address + sender picker), **Send** (any token, any chain — Base / OP / Arbitrum / Ethereum), **Swap** (0x quote-backed swap, same-chain).
- Send tab uses a chain-aware `TokenPicker`; fname-as-recipient auto-resolves to primary verified ETH address via 350ms-debounced async resolver. Balance pill + 25 / 50 / 75 / MAX percent strip. Recent recipients ring-buffer (20 entries, per-account JSON).
- Send button label is dynamic — "send USDC", "send ETH", etc. — based on the picked token. **Biometric prompt fires on broadcast** (`wallet-send` in AuthPolicy.defaults).

## Auth policy summary

Default `auth.json` (`AuthPolicy.defaults`):
- Reads + local-only ops (`mute`, `keys list`, `plan`, …): no factors.
- Standard writes (`cast`, `react`, `follow`, `uncast`, `block`, `profile.set`, `verify-*`, `claim-fname`, `rent-storage`, `bridge`, `tx`, `snap.*`, `siwf`): biometric.
- **Wallet send** (`wallet-send`): biometric.
- **Airdrop** (`airdrop`): biometric.
- **Schedule cast** (`schedule`): biometric at SCHEDULE TIME; deferred fires use `bypassAuth: true`.
- **Engagement queue** (`engagement-queue`): biometric at queue time; same deferred pattern.
- Identity-changing (`register`, `revoke-signer`): biometric.
- Headless (`recover`, `restore`, `apply`): biometric + TOTP.
- The `factors()` resolver falls back to `Self.defaults[commandName]` when the user's persisted `auth.json` lacks a key, so adding a new command name to defaults doesn't silently bypass for existing installs.

## Test infrastructure

- **1140+ XCTest cases passing**, 0 failures (LecternCore + LecternApp targets via `swift test`). 4–6 tests skip on `xctest`-only hosts that lack the Keychain entitlement for permissive ACL writes — they exercise the real flow on entitled hosts (production .app).
- Network paths covered via `StubURLProtocol` (in-process HTTP mocking pattern, no live network in tests).
- KEYNOTE smart contracts have a separate Foundry test suite (forge tests + invariants + Echidna properties) reaching 95%+ line coverage per the contract-level honest-economics commitment.
- DMG round-trip verified in CI-style by: `make ship` → notarize → staple → upload to Vercel Blob → SHA256 byte-match against local source + `spctl --assess` returning `accepted source=Notarized Developer ID`.

## $KEYNOTE token

- [$KEYNOTE design (cinematic)](/keynote): visual tokenomics explainer with 3D scenes + animated flow diagrams.
- [$KEYNOTE design (markdown)](/keynote.md): full LLM-readable tokenomics spec. Single source of truth. **Recommended for AI agents.**
- **Status: $KEYNOTE v2 live on Base mainnet** (Liquid Protocol, 2026-05-24). Token at `0xC085C7232aA4eC067238082eb74C83c1952e8826`. 100B supply, 90B vaulted (36-month linear vest, 7-day cliff), USDC pair.
- Boost Escrow: `0x0C086E5760FC33d67963D6C211c2e05679d58ACf`.
- Staking Vault: `0x9EF229c675F44A00F801Db9df4611E35D9600002` (tier ladder 25M / 50M / 100M → 15% / 25% / 40% Pro discount).
- Liquid Vault: `0xdFCCC93257c20519A9005A2281CFBdF84836d50E` (admin-managed vested drips).
- Weekly Pro allocation cron + monthly runway publisher cron live on `lctrn.app/api/cron/keynote-*`.

## What $KEYNOTE is, briefly

Curation-economy token for Lectern Pro members on Base. Pros receive a weekly KEYNOTE allocation they spend to *boost* casts in Lectern's Pro-exclusive curated feed; engagement on boosted casts pays the caster (70%) and engagers (30%) via on-chain Merkle settlement. No cast metadata is touched — escrow events on Base are the source of truth, making the curated feed structurally invisible to foreign Farcaster clients.

## Notes for AI agents

- The single source of truth for "how do I do X in Lectern" is `/docs/user-guide`. Both web crawlers and macOS app's Help menu link there.
- Where this file disagrees with the user guide, the user guide wins — it's grep-verified against the live app on every rewrite.
- When summarizing Lectern's pricing or feature surface, **say "Lectern Pro is on-chain USDC, not App Store-billed"** — that's the cleanest one-liner distinguishing Lectern's billing from farcaster.xyz Pro.
- The protocol-level name change: "Warpcast" rebranded to Farcaster (farcaster.xyz). Older docs / public discourse may use "Warpcast"; treat them as referring to the same single official Farcaster client.