Changelog
Version history for all user guides
Version History
Track changes across all Hyphen user guides. Each guide is independently versioned and updated when the corresponding platform feature changes.
June 2026 (2026-06-23) — post-overhaul refresh + FAQs
Every guide was reviewed against the ~10 days of feature work that landed after the 2026-06-13 overhaul and updated to current behavior, grounded in the actual code (not just commit messages). A Frequently Asked Questions (FAQ) section was added to every guide (the Editorial guide's existing FAQ was expanded), with deeper FAQ coverage on the entitlement-heavy guides — Subscriptions, Paywall & Access, Sales, Reader Management, Future Readers, and Magazine. Screenshots of surfaces that changed in this window are flagged for a re-capture pass.
| Guide | Version | Changes |
|---|---|---|
| Reader Management | 1.7 | Reader account pages redesigned (Account, Subscription, Preferences, Notifications card layout, Sessions, Activity, Bookmarks with delete-confirm, Reading History with author/translator + Clear All); reader search extended to contributors, books, and events; new FAQ (reader access & entitlements). |
| Editorial & Content | 1.7 | Designer role and S6B state removed; typesetting gate (S7→S8) now precedes Publish/Schedule; combined category + language reader filters; reading-time + publication-date article headers (book-aware); single + bulk Unpublish; auto-unpublish when an article's last issue link is removed; FAQ expanded. |
| Paywall & Access | 2.1 | Content Protection now enforced site-wide via a global controller (independent of the Enable-Paywall switch); read-quota reset moved to billing-period start (free tier keeps the calendar-month anchor); current paywall/overlay copy; visible_in_listings tier note; new 17-item FAQ. |
| Subscriptions | 2.1 | Coupon entry at checkout with plan/interval validation; Terms/Privacy sign-in gate; dynamic gift plans + pre-payment recipient-eligibility check; OTP + Terms gift/institutional activation gate; institutional invited→active seats; admin Delete-Plan (migrate vs deactivate); 21-item FAQ. |
| Sales System | 1.6 | Institutional seats now track invited → active → deactivated (seat consumed while invited, access only when active, promoted on first magic-link login); gift recipient eligibility + OTP/Terms activation gate; coupon-at-checkout; member-status lifecycle diagram; 14-item FAQ. |
| Magazine Issue Management | 1.7 | Flipbook free preview for gated issues (N-page cover + editor's note, contiguous from page 1) via the flipbookFreePreviewPageCount control; Hyphen-design immersive reader at /issue/[slug]/read; flipbook PDF URL limit raised to 2048 chars; 12-item FAQ. |
| Events Management | 1.2 | Template-driven rendering; computed Live/Upcoming/Past lifecycle (Live needs an End Date) with Join-now for online events; Related Events on event detail pages; manual selection + lifecycle filter; Online Details field; campaign-event leak fix; new FAQ. |
| Email System | 1.6 | Documented the single wrapEmailWithPreferences branding/brand-color chokepoint and brand fonts; template-driven OTP; account_welcome vs subscription_welcome; the gated /start CTA; the rich-text Notices Body editor; the Purposes "Test connection" dialog; new FAQ. |
| Marketing Features | 1.2 | New Marketing Inbox triage hub consolidating Campus Inquiries + Contact + Feedback Submissions with per-stream RBAC; dynamic Explore-By-Language sourcing; updated process-flow diagram; new FAQ. |
| Marketing Operations | 1.2 | Hyphen Connects overhaul: per-lifecycle-state campaign templates (campaign-<type>-<state> → campaign-<state>), contest tab grouping, post-event summaries; campaign + per-session start/end times; Marketing Inbox; new FAQ. |
| Page Templates | 1.4 | New static-page variants/surfaces — Masthead, Press Releases (listing + detail, media contact/coverage, gallery), Authors & Translators showcase + contributor page, FAQ multi-column layout with category picker, Related Events; corrected faq-accordion to a listing behavior; new FAQ. |
| Layout & Design Templates | 1.4 | Reader-facing per-grid filters (Language/Author/Section) on grid variants; expanded Figma design-token / appearance reference (CTA color, border style/radius, tag & badge colors, section-nav style, etc.); curated vs reader-facing filter distinction; new FAQ. |
| Conversion Surfaces | 1.2 | Documented adjacent code-driven conversion entry points — the paywall overlay (current metered copy/CTA), the Terms-acceptance auth gate, and the gated /start route used by email CTAs (noting these aren't tracked in conversion_events); new FAQ. |
| E-Commerce Store | 1.2 | Dual-currency (₹ / $) Featured Book cards via priceUsd presentment-price sync; clarified Shopify product stock vs the magazine Current-Issue print-inventory toggle; corrected the API version + a price-unit example; new FAQ. |
| Analytics & Reporting | 1.2 | GA4 now authenticates via Application Default Credentials when no service-account key is set (the key is no longer required); removed the non-configurable GA4_CACHE_TTL_MS; verified dashboards/metrics/crons unchanged; new FAQ. |
| Analytics Features | 1.2 | GA4 ADC auth note; corrected event-wiring status (article/paywall/shop/registration events now wired; subscribe/newsletter events still pending); listed the extra navigation/discovery events; new FAQ. |
| Moderation System | 1.2 | Corrected the reader comment endpoint path; noted comment/report rate limits are now Redis-backed with in-memory fallback (limits unchanged); verified spam scoring, statuses, trusted flag, and report handling; new FAQ. |
| Future Readers Program | 1.2 | Coupon redemption now fully wired into reader checkout (promo field + auto-applying ?coupon=); region gating of the Students/Gift pricing cards (INR); reader-tier classification feeding the directory; new 13-item FAQ. |
| Social Media Management | 1.2 | Verified accurate against current code (no user-facing changes this cycle); new FAQ. |
June 2026 (2026-06-13) — comprehensive technical-reference overhaul
Every feature guide was deepened from a step-by-step walkthrough into a complete technical reference, while keeping the friendly tone. Each guide now adds, where applicable: How It Works (Behind the Scenes) (end-to-end data flow across Admin Console → Postgres/Prisma → Strapi → Reader Portal, with Mermaid flow diagrams), a Configuration Reference (every field/option/variable with type, mandatory, default, where configured — UI vs backend/env — and the role that can set it), Concepts & methodology explanations, and a Dependencies & Impact section cross-linking related guides. Fresh screenshots were captured from both the Admin Console and the Reader Portal. Mermaid diagram rendering (with PDF-export support) was added to the docs site, and a reader-portal screenshot harness was introduced.
| Guide | Version | Changes |
|---|---|---|
| Editorial & Content | 1.6 | Added How It Works data flow, an editorial-workflow state diagram, expanded access/visibility detail, Dependencies & Impact, and a reader article-reading screenshot. |
| Page Templates | 1.3 | Added How It Works, "The Template System Explained" (page type → template → variant → section hierarchy), render-resolution diagram, and Dependencies & Impact. |
| Layout & Design Templates | 1.3 | Converted the architecture, template-lifecycle, and email-pipeline diagrams to rendered Mermaid; clarified the boundary with Page Templates; deep Configuration Reference. |
| Magazine Issue Management | 1.6 | Added the issue/TOC data model, the four-tier magazine access ladder resolution diagram, protected flipbook delivery detail, Configuration Reference, and reader issue-viewer screenshots. |
| Subscriptions | 2.0 | Major expansion: subscription lifecycle state diagram, billing/payment model (Razorpay/Stripe), entitlement resolution, gifting/upgrade/cancel flows, Configuration Reference, Dependencies & Impact. |
| Reader Management | 1.6 | Added plans & structured entitlements (boolean/numeric) concepts, institutional/bulk grant flow, How It Works, and a full Configuration Reference. |
| Paywall & Access | 2.0 | Expanded from a stub: access-level enum, entitlement-bit resolution cascade, magazine access ladder, crawler verification, preview tokens/coupons, Configuration Reference. |
| Future Readers Program | 1.1 | Documented the enrollment lifecycle, institutes, the coupon-based access-grant mechanism, How It Works, and Configuration Reference. |
| Sales System | 1.5 | Added the deal pipeline state diagram, institution/institutional-subscription model, provisioning & renewal flow, and Configuration Reference. |
| Marketing Features | 1.1 | Added segmentation/campaign/coupon concepts with lifecycle diagrams, How It Works data flow, and Configuration Reference. |
| Marketing Operations | 1.1 | Added campaign-type taxonomy, newsletter-edition lifecycle, How It Works, and Configuration Reference. |
| Conversion Surfaces | 1.1 | Documented surface types/placements, the targeting model, the impression→conversion funnel, and accurate trigger/frequency/suppression defaults. |
| Email System | 1.5 | Added purpose→account routing and the four email-class taxonomy, template-variable reference, provider env vars, How It Works, and Configuration Reference. |
| Social Media Management | 1.1 | Added OAuth account-linking, post-lifecycle state diagram, publish/metrics cron flow, and Configuration Reference (OAuth env vars). |
| Analytics & Reporting | 1.1 | Documented the first-party-vs-GA4 source-of-truth model, event taxonomy, snapshot/alert crons, and Configuration Reference. |
| Analytics Features | 1.1 | Clarified how content-performance (GA4) and subscription metrics (Prisma) are derived, with derivation diagrams and a metrics reference. |
| Moderation System | 1.1 | Added the multi-signal spam-scoring model, comment lifecycle + report-handling diagrams, and a thresholds/actions Configuration Reference. |
| E-Commerce Store | 1.1 | Documented the Shopify integration model (Storefront vs Admin API), catalog sync, localStorage cart + checkout redirect, and env-var Configuration Reference. |
| Events Management | 1.1 | Expanded from a stub: corrected the model (Prisma-owned, one-way Strapi sync), registration/capacity flow, and Configuration Reference; added a reader Events screenshot. |
Late May 2026 (2026-05-30) — documentation sync
Reconciliation of the user guides with the late-May 2026 code state (subscription reader-directory close-out BUG-SUB-30MAY-01..09, the magazine access-tier work BUG-MAG-29MAY-01/02, and the 2026-05-30 email audit).
| Guide | Version | Changes |
|---|---|---|
| Subscriptions (new) | 1.0 | New reader-facing guide for the self-service subscription journey: plan catalog, 3-step checkout (details/address → plan + billing interval + coupon → payment), Razorpay / Stripe / Dummy gateways, coupons, gift subscriptions (purchase → activation), upgrade/downgrade with proration preview, period-end cancel, renewal / win-back reactivation, and the My Subscription + Subscription History pages (entitlements + print delivery status). |
| Reader Management | 1.5 | Late-May admin reader-directory close-out: plan Catalog Dimensions (Audience / Delivery format / Supported billing intervals); plan-aware grant (Digital → interval; Print → issues; Bundle → both); typed-CANCEL guard + churn reason; Extend hidden on dead subs with Reactivate / Grant New / Send Payment Link; purple "Managed via Institutional Subscription" lock banner. Corrected Dummy-mode gating reference. |
| Sales System | 1.4 | Plans now carry an Audience dimension — institutional plans are filtered out of every self-service / individual flow. Cross-linked the new Subscriptions guide. |
| Email System | 1.3 | New Event Registry (Settings → Email → Events, BUG-EMAIL-FU-016 — closes EMAIL-HIGH-003): the Event → Purpose → Account → Template table with a per-event kill-switch (mandatory-transactional exempt, fail-open), send-sample-to-self with dry-run, and a Retired badge (§8a). Plus the 2026-05-30 email-audit reconciliation: §14a Known limitations, §16 QA / UAT checklist, and the architecture reference repointed to the canonical doc + API spec §11. |
| Paywall & Access | 1.3 | New Magazine Issue Access Tiers ladder (Free / Restricted Free / Premium Limited / Subscriber Only mapped to plan entitlement bits, with /login vs /subscribe redirects); the issue-level default + per-article TOC override authoring model and effective-access cascade; legacy magazineAccess back-compat note; legacy-plan entitlement shim. New access-tier QA scenarios. |
| Editorial & Content | 1.5 | Heads-up that magazine article access is moving to the Issue Editor (issue default + TOC override, four-tier ladder); the per-article Article visibility dropdown is retained for backward compatibility. |
| Magazine Issue Management | 1.5 | Documented the issue-level access model (default + TOC override) and the new Issues-list Access column (replaced the dropped Frequency column); cross-linked Paywall & Access. |
May 2026
| Guide | Version | Changes |
|---|---|---|
| Reader Management | 1.4 | 2026-05-01 (post-launch hardening) — Magazine Schedule admin gains the missing Issue picker (searchable, includes drafts so admins can pre-map upcoming issues), an inline Edit modal, a Generate Year bulk action (12 placeholder rows in one click, idempotent), a green-dot indicator showing rows that will produce entitlements (Active + published Issue mapped), and a critical bug fix: toggling Active no longer wipes the mapped Issue. New Regenerate Entitlements button on Schedule + Print Fulfilment empty-state — operator-triggered recompute for existing subscribers after a schedule edit (idempotent). Print Fulfilment dropdown now lists published Issues correctly (the page was previously stuck on "Loading…" due to a wrong endpoint). New first-time configuration sequence added at Subscriptions → Magazine Schedule with explicit "create Issue → Generate Year → map each row → simulate subscription" walkthrough. Dummy Payment Mode gating revised: default ON; opt out via DUMMY_PAYMENT_MODE_ENABLED=false on the production process (the previous NODE_ENV gate didn't work on UAT because Next.js bakes production into every deployed build). When Dummy is on, it's the only payment option on checkout — Razorpay/Stripe tiles are hidden so operators can't accidentally pick a broken gateway. Paywall fix: plans seeded with the legacy features format now correctly grant paid-tier access to subscribers (accessPremiumArticles / accessDigitalIssues / accessPaidNewsletters / adFreeExperience / earlyAccess). Server-side address validation now blocks Print activations with incomplete shipping fields (clearer error than the previous silent acceptance). |
| Magazine Issue Management | 1.4 | 2026-05-01 (post-launch hardening) — When an article is attached to an issue, its visibility is now auto-defaulted based on the article's access level: subscriber-only / premium → Magazine — subscribers only; free → Magazine — registered readers only. Articles whose visibility is already explicitly set are not touched — the editor's choice via the article editor's Article visibility dropdown is authoritative. When an article is removed from its last issue, visibility is reset to Public so the article can re-appear in section / home / search listings. New backfill script available for existing rows. |
| Reader Management | 1.3 | 2026-05-01 — Subscription Module Refactor lands. New §5.4a Print Fulfilment List (per-issue list with address-completeness highlight, bulk Mark Dispatched, duplicate-export guard at Readers → Subscriptions → Fulfilment). New §5.12a Dummy Payment Mode (UAT-only gateway with two-key env gate DUMMY_PAYMENT_MODE_ENABLED + ALLOW_DUMMY_IN_PROD; Simulate Success / Simulate Failure buttons; never calls Razorpay). New §5.13a Label Templates (CRUD at Settings → Labels: 2×1 / 3×2 thermal + A4 24-up; CSV + printable HTML export; address-only by default; PDF/Excel binary tracked as a follow-up dep-add). §5.3 Plan editor extended: Issues / Days / Months duration toggle, Print Fulfilment & Inventory section (Shopify product mapping, Current issue unavailable behaviour HIDE/DISABLE/SHOW_WITH_MESSAGE), Allow Renewal toggle. §5.4 Checkout now captures structured address (Address Line 1/2, Landmark, City, State, Country, PIN) with Save to my profile opt-in; live current-issue stock check at Pay with auto-downgrade to Next Issue and 503-on-Shopify-failure rather than silent over-promise. §5.6 Institutions now record Offline Payment Mode + Reference + Date. §5.8 New /account/subscription/history page lists current subscription, payments (Dummy badge), and per-issue entitlements with fulfilment status. |
| Email System | 1.0 | 2026-05-01 — New top-level guide. Documents the multi-account email routing system that replaces the legacy single-EmailConfiguration singleton. Covers Email → Dashboard / Templates / Accounts / Purposes / Suppressions / Logs, the per-purpose mapping table, the Save & connect setup flow, Verify connection vs Send test email diagnostics, the suppression list, and reading the dashboard / logs. Includes a "What changed (vs older Settings → Email)" mapping table. |
| Marketing Features | 1.2 | 2026-05-01 — Updated email-setup verification flow to point at Settings → Email → Accounts (was Settings → Email → SMTP Status). Added pointer to the new Email System Guide. Adjusted the Email branding path (now under Settings → Email → Templates → Preferences). |
| Marketing Operations | 1.2 | 2026-05-01 — Setup checklist refreshed for the new Email IA: items now cover account creation, purpose mapping, and template purpose assignment as separate steps. Troubleshooting and pre-test checklist references repointed to Settings → Email → Accounts/Purposes/Templates. |
| Editorial & Content | 1.4 | 2026-05-01 — Setup checklist's email row updated: account configuration via Settings → Email → Accounts → Verify connection; editorial_workflow purpose mapping noted at Settings → Email → Purposes. |
| Sales System | 1.3 | 2026-05-01 — Institutions creation form gains an Offline Payment section (Mode / Reference / Date) per Subscription Module Refactor §9.2. Captures the bank transfer / cheque / cash / other mode plus a free-text reference so Finance has a clean audit trail for institutional commercials negotiated outside the platform. |
| Sales System | 1.2 | 2026-05-01 — Pre-launch checklist email row repointed; troubleshooting updated to call out the subscription_lifecycle and inquiry_followup purpose mappings. |
| Reader Management | 1.2 | 2026-05-01 — OTP / password-reset / notification email row repointed to the new Email IA. Troubleshooting "Email not working" updated to reference Verify connection and the per-purpose mapping check. |
| Layout & Design Templates | 1.2 | 2026-05-01 — §7 (Email Template System) updated to reflect the new Email sidebar group; old paths for Email Configuration (/settings/emails/config, retired and redirecting) and the legacy single-SMTP page replaced. Added pointer to Email System Guide. |
April 2026
| Guide | Version | Changes |
|---|---|---|
| Editorial & Content | 1.3 | 2026-04-29 — Renamed the article editor's tier dropdown from Magazine Access to Article visibility, and reframed the three options as positive declarations of audience: Public — appears in home, sections, search / Magazine — registered readers only (hidden from public listings) / Magazine — subscribers only (hidden from public listings). The internal field and data values are unchanged; this is a presentation reframe so all three options speak in the same vocabulary. |
| Magazine Issue Management | 1.3 | 2026-04-29 — Updated §5.6, key terms, and troubleshooting tables for the Article visibility relabel (was Magazine Access). |
| Editorial & Content | 1.2 | 2026-04-28 — Added the new Magazine Access tier dropdown on the article editor (FEAT-MAG-ACCESS-TIER). Replaces the old "Appears only in magazine issue" checkbox with three options: Not magazine-only / Free to magazine readers / Magazine-exclusive. |
| Magazine Issue Management | 1.2 | 2026-04-28 — Documented the per-article Magazine Access tier and the reader experience for each tier. New §5.6 (setting the tier on an article), new §6.5 (verifying tier behaviour on the Reader Portal), new §7 (what readers see), updated key terms, expanded QA checklist with magazine-access scenarios. |
| Editorial & Content | 1.1 | Added screenshots, updated workflow steps for new triage UI, added FAQ management |
| Marketing Features | 1.1 | Added screenshots, updated campaign wizard steps, added conversion surfaces |
| Page Templates | 1.1 | Added screenshots, updated section properties panel, added banner configuration |
| Analytics & Reporting | 1.1 | Added screenshots for dashboard, analytics overview, social analytics, and exports |
| Reader Management | 1.1 | Added screenshots for reader directory, subscriptions, institutional access, moderation |
| Social Media Management | 1.1 | Added screenshots for accounts, composer, calendar, campaigns, and analytics |
| Layout & Design Templates | 1.1 | Added screenshots for template editor, email templates, and appearance settings |
| Magazine Issue Management | 1.1 | Added screenshots for issue list, issue editor, and publishing schedule |
| Magazine Issue Management | 1.0 | Initial release — issue lifecycle, table of contents, publishing, scheduling, archiving, SEO, analytics |
| Moderation System | 1.1 | Added screenshots for moderation dashboard, comment queue, and user moderation |
| E-Commerce Store | 1.1 | Added screenshots for store settings, product catalog, and order management |
| Sales System | 1.1 | Added screenshots for institutions list, sales pipeline, and reports |
| Future Readers Program | 1.1 | Added screenshots for institutes list and enrollment review queue |
| Marketing Operations | 1.1 | Added screenshots, migrated to docs site |
| Analytics Features | 1.1 | Added screenshots for dashboard and analytics overview |
| Conversion Surfaces | 1.1 | Added screenshots for surface list and analytics |
March 2026
| Guide | Version | Changes |
|---|---|---|
| Editorial & Content | 1.0 | Initial release |
| Marketing Features | 1.0 | Initial release |
| Page Templates | 1.0 | Initial release |
| Analytics & Reporting | 1.0 | Initial release |
| Reader Management | 1.0 | Initial release |
| Social Media Management | 1.0 | Initial release |
| Layout & Design Templates | 1.0 | Initial release |
| Magazine Issue Management | 1.0 | Initial release |
| Moderation System | 1.0 | Initial release |
| E-Commerce Store | 1.0 | Initial release |
| Sales System | 1.0 | Initial release |
| Future Readers Program | 1.0 | Initial release |
Guides are updated whenever platform features change. Screenshot captures are regenerated automatically using the screenshot pipeline.