BDMurphy BookShelf
WordPress System
Technical Specification
Version 2.0  ?  May 2026
Theme: BDMurphy-Bookshelf    Plugin: BDMurphy-BookShelf    Plugin: BD-BookShelfHelper

1. Project Overview

1.1 Purpose
This specification defines a custom WordPress theme and two companion plugins for author B.D. Murphy's website. The system allows the author to showcase books, publish blog posts, manage reviews, and send newsletters with minimal technical knowledge required after initial setup. The theme is built from scratch with no parent framework and follows WordPress coding standards throughout.
The core design principle is enter once, display everywhere: the author enters book details once in the BD-BookShelfHelper plugin and the system generates all book pages, series pages, and review displays automatically. No individual page creation or editing is required for book content.

1.2 Deliverables
Theme: BDMurphy-Bookshelf	Custom WordPress theme. Fully Customizer-driven. Follows WordPress standards and best practices. Provides the visual presentation layer for all pages. Ships with default logo, banner, and sample content.
Plugin: BDMurphy-BookShelf	Manages the home page book shelf sidebar widget, subscriber sign-up, subscriber management, and email newsletter creation and delivery. Includes AI-assisted newsletter composition via the Gemini API.
Plugin: BD-BookShelfHelper	The book data management plugin. Stores all book information (blurbs, genres, reviews, cover images), series, and pen names. Generates book pages, review pages, and series pages from entered data. Manages short links, review links, Goodreads integration, Amazon ratings, and SEO. Full specification: BD-BookShelfHelper-Plugin-Specification-v1_0.docx.

Each deliverable package includes: a description, a setup and customization guide, and a display visual for the WordPress plugin or theme directory listing. Each deliverable is a ready-to-upload package installable via the WordPress admin. Deliverables are built one at a time and tested individually before integration testing.

1.3 Design Identity
     Logo: Quill-pen hybrid icon with "B.D. Murphy" in serif text  provided asset ships as default (BD_BookShelf_Logo.png).
     Banner: 1200250px illustrated timeline (scrolls from quill to modern ebooks)  ships as default (Reading_through_time.png).
     Palette: Navy blue (#1B3A6B) primary, warm gold (#C8A96E) accents, parchment (#F5F0E8) background.
     Typography: Playfair Display / Georgia fallback for headings; Lato / Calibri fallback for body.
     Mood: Cozy, casual reading  literary but not stiff. Light mode only; no dark mode.

1.4 General Behavior
     All content displays in reverse chronological order by first-published date unless a manual sort position is assigned.
     Series content sorts by volume number within the series.
     UI chrome (menus, labels, system text) follows the site language setting; content stays in the language it was authored in.
     All purchase links support affiliate code injection, applied server-side using per-retailer URL patterns.
     All short links share one conflict-check pool  no slug can clash with any other WordPress slug.
     The site represents one author who may publish under multiple pen names. The site header and bio always reflect the author identity; book pages show the pen name the book was published under.

2. Theme  Global Layout

2.1 Header
     The author's logo, sized to 250250px, appears at the top left of every page. BD_BookShelf_Logo.png ships as the default.
     The banner image, 250px high, appears to the right of the logo and is centered on the page. Reading_through_time.png ships as the default.
     The logo and banner are the first elements on every page, above the navigation.
     Both are implemented as WordPress configurable items. The author replaces them via Appearance > Customize > Header Image.
     The default site title is the website URL. The default tagline (blogdescription) is "Expand your mind."
     Site title and tagline display as text fallback when no banner image is set.
     Nothing appears above the banner except the browser chrome and the WordPress admin bar (32px when logged in). Admin bar offset handled via body.admin-bar rules.
Note: Banner height is locked at 250px maximum in the custom-header declaration.

2.2 Navigation Menu
Registered via register_nav_menus(['primary' => 'Primary Menu']). Assigned in Appearance > Menus.
Sits directly below the banner with zero gap. Spans 100% viewport width. Background: navy (#1B3A6B). Active item: white text with gold 2px underline.

Default Menu Items
Home  Blog  Books  Reviews  Series  About  Register
Each item has a pre-built default page installed at theme activation with simple example content.

Home	General news and blog posts. Two-column layout (see Section 3.1).
Blog	WordPress posts listed in date order, most recent first. Posts tagged as blog posts (not reviews).
Books	All books page. Ships with "Pandemic Hacker" as sample content.
Reviews	Without BD-BookShelfHelper: WordPress posts tagged "reviews". With BD-BookShelfHelper: generated review display page showing review information in multiple languages with pull-quote callouts.
Series	Without BD-BookShelfHelper: standard WordPress page with two sample book entries. With BD-BookShelfHelper: generated series listing from plugin data. The Series nav item is hidden when no series records exist.
About	Standard WordPress page with author biography and details (see Section 3.6).
Register	Sign-up page for newsletter and announcement subscriptions (see Section 3.8). Managed by the BDMurphy-BookShelf plugin.

When BD-BookShelfHelper is installed, a language selector dropdown appears right-justified at the far right of the navigation bar. The default language is configured in settings (default: EN).
When BDMurphy-BookShelf plugin is installed, the Register page provides selection for opt-in / opt-out of categories: Newsletter, New Book Announcements, and Events. Registered users can return to this page to update their preferences.

Sticky Behavior
     Default: sticky  CSS position: sticky; top: 0; z-index: 100. Pins to viewport top as user scrolls past the banner.
     When sticky and the banner has scrolled out of view, a 2px gold top border appears on the nav bar.
     body.admin-bar .site-nav { top: 32px } applied when the WordPress admin bar is visible.
     All in-page anchor targets use scroll-margin-top: 48px to avoid content being hidden behind the sticky nav.
     A Theme Options toggle (sticky_nav, default: true) allows disabling sticky behavior.
Note: Sticky nav requires the nav parent element to have defined height, not overflow: hidden.

2.3 Footer
     Three-zone layout: social icons (left), donate buttons (centre), utility links (right).
     Social links: X/Twitter, Facebook, LinkedIn, Instagram, BlueSky. URLs configured in Appearance > Theme Options > Social Media.
     "Buy Me a Coffee" and PayPal donate URLs configured in Appearance > Theme Options > Donate Links.
     Utility links: Contact | About | Privacy Policy | Unsubscribe  registered as footer menu via register_nav_menus(['footer']).
     Footer also includes a brief sign-up prompt with a link to the /signup/ page.
     Two registered widget areas: "Footer Left" and "Footer Right"  available in Appearance > Widgets.

2.4 WordPress Customizer Settings
All visual settings are exposed through the WordPress Customizer (Appearance > Customize) using standard WordPress APIs.

Setting	WordPress mechanism / function	Admin location
Site title	get_bloginfo('name') / Settings > General	Customizer > Site Identity
Tagline	get_bloginfo('description')	Customizer > Site Identity
Logo upload	add_theme_support('custom-logo') / the_custom_logo()	Customizer > Site Identity > Logo
Banner image	add_theme_support('custom-header') / get_header_image()	Customizer > Header Image
Page background	add_theme_support('custom-background') / default #F5F0E8	Customizer > Background
Primary color	get_theme_mod('primary_color', '#1B3A6B')	Customizer > Colors > Primary
Accent color	get_theme_mod('accent_color', '#C8A96E')	Customizer > Colors > Accent
Heading font	get_theme_mod('heading_font', 'Playfair Display')	Customizer > Typography > Headings
Body font	get_theme_mod('body_font', 'Lato')	Customizer > Typography > Body
Primary navigation	register_nav_menus(['primary'])	Customizer > Menus
Footer navigation	register_nav_menus(['footer'])	Customizer > Menus
Footer widgets	register_sidebar() x 2	Customizer > Widgets > Footer

Note: All get_theme_mod() calls include a default value so the theme displays correctly immediately after activation.
Note: Colors output as CSS custom properties (--bdm-navy, --bdm-gold, --bdm-cream, etc.) via the wp_head hook.

2.5 Theme Options Admin Screen
Settings that do not suit live Customizer preview are in Appearance > Theme Options, saved via the WordPress Settings API.

Social: X/Twitter URL	URL for X/Twitter profile  displayed as icon in footer.
Social: Facebook URL	URL for Facebook page.
Social: LinkedIn URL	URL for LinkedIn profile.
Social: Instagram URL	URL for Instagram profile.
Social: BlueSky URL	URL for BlueSky profile.
Donate: Buy Me a Coffee URL	Full URL to buymeacoffee.com page.
Donate: PayPal URL	Full PayPal.me or donation URL.
Donate: Venmo URL	Full Venmo donation URL.
Author photo	WordPress media attachment ID  defaults to built-in smiley SVG when empty.
Sticky navigation	Boolean toggle, default: ON.
Posts per page (blog)	Integer, default: 10.
Language default selection	Dropdown: EN, FR, DE, ES. Shown in the language selector when BD-BookShelfHelper is active.
Show read time on posts	Boolean, default: ON. Displays estimated read time on blog posts.
Business name	Legal name  appears in email footer for CAN-SPAM compliance.
Business address line 1	Street address  required for CAN-SPAM.
Business address line 2	Suite, unit, PO Box  optional.
City / State / Postal code	Required for CAN-SPAM.
Country	Required for CAN-SPAM.
Phone number	Optional  appears in email footer if provided.
Note: Business information fields are required by CAN-SPAM law for commercial email. The BDMurphy-BookShelf plugin pulls these values into every outgoing email footer automatically.

3. Theme  Pages

3.1 Home Page
Template: front-page.php. Set as static front page via Settings > Reading.
Two-column layout: left 66%, right 34%.

Left Column  News & Blog
     Content managed via the WordPress block editor on a WordPress Page. No custom meta fields.
     Editorial, hand-curated. Author news, announcements, featured blog post headings.

Right Column  Book Shelf Widget
     Without the BDMurphy-BookShelf plugin installed: a placeholder widget displays "BDMurphy-BookShelf Plugin recommended."
     With BDMurphy-BookShelf plugin: custom WordPress widget registered by the plugin, placed in the "Home Sidebar" widget area.
     Each entry: cover thumbnail (4462px), Amazon and Goodreads star ratings, retailer icon row.
     Clicking any cover navigates to that book's individual detail page. If BD-BookShelfHelper is not installed, the link goes to the /books/ page.
     BD-BookShelfHelper creates the detail page for each book when book data is entered. It displays details based on the reader's selected language.
     Sorted by publish date newest first unless manual order is set.

3.2 Blog Page (/blog/)
Template: archive.php or home.php. Set as posts page in Settings > Reading.
     Lists all published blog posts, newest first: title (linked), date, category tag, excerpt (~150 words), featured image thumbnail (10068px).
     Paginated  10 posts per page, configurable via Theme Options.
     Social sharing buttons at the bottom of each individual blog post (see Section 3.9).

3.3 All Books Page (/books/)
Template: archive-book.php. Stacked list, most recent first. If series exist, a "Browse by series" link appears at the top pointing to /series/.
     Each entry: cover image (130185px, left), author pen name, title, ratings, format toggle, retailer buttons, blurb, and review excerpt.
     Format toggle (Ebook / Paperback / Hardback) filters retailer buttons. Ebook-only retailers (Apple Books, Google Play) disabled when Paperback or Hardback is selected.
     All retailer links include affiliate codes applied server-side.
     BD-BookShelfHelper provides an "Update Links" button to scan retailer websites and verify purchase link URLs.
     If a book belongs to a series, a "Part of [Series Name]" label links to /series/{slug}/.

3.4 Individual Book Page
Template: single-book.php. Canonical URL is the book's short slug (e.g. /ph/). Full-width template  no sidebar.

Page Content (Top to Bottom)
     Language selector tab bar (EN FR DE ES RU ZH-S)  switches title, blurb, and pull quotes to the selected language version.
     Cover image (220310px), prominent, left-aligned.
     Book title and pen name (the name the book was published under).
     If the book belongs to a series: "Part of the [Series Name] series  Book [volume number]" displayed below the title. The series name links to /series/{slug}/. Styled similarly to Amazon's series display.
     Amazon and Goodreads star ratings.
     Format toggle (Ebook / Paperback / Hardback)  dark green active state.
     Retailer purchase buttons with affiliate codes.
     "Read preview" section and one-liner pull quotes.
     Review cards (comment text, source name, optional source link).
     Back-cover blurb.
     Share button  copies the book's short URL to clipboard with a toast confirmation. The short URL (e.g. authorbdmurphy.com/ph) is shared, not the full canonical URL.
     Social sharing buttons at bottom of page (see Section 3.9).

3.5 Reviews Page (/reviews/)
Template: page-reviews.php. Two-column card grid, sorted by book publication date newest first.
     Each card: book cover thumbnail (5274px), title, review count, up to 3 review entries.
     Per review entry: source name (uppercase blue) + 3-line AI-generated synopsis (italic).
     Clicking a card or "View all reviews" opens the per-book review detail page.
     Review detail page: cached WordPress page with table of contents (anchor links) and full review text. Anchor targets use scroll-margin-top: 48px for sticky nav clearance.
     Generated or regenerated when a review is added in BD-BookShelfHelper or the author triggers regeneration.

3.6 About Page (/about/)
Template: page-about.php. Two-column layout.

Left Column
     Author real name and pen name(s) used  listing pen names is optional.
     Full biography text  entered via the WordPress block editor. One bio for the author (not per pen name).
     Awards list with gold dot markers.
     "Buy Me a Coffee" button and PayPal donate button  URLs from Theme Options.
     Sign-up prompt: a short "Stay updated" section with a link to the /signup/ page.

Right Column Sidebar
     Author photo: defaults to built-in smiley face SVG. Replaced via Appearance > Theme Options > Author Photo.
     Sign-up card: brief description + "Sign up for updates" button linking to /signup/.
Note: The About page bio is for the author as a person. Pen names listed here are informational only. Each book page shows the pen name the book was published under.

3.7 Series Pages
Series pages appear only when series are configured in BD-BookShelfHelper. The Series nav item is hidden when no series records exist.

Series Listing Page (/series/)
     Template: archive-series.php.
     Each series shown as a card: series cover graphic, series name (heading), series blurb/description, book count.
     Cards sorted by series creation date (most recent first) or manual order set in BD-BookShelfHelper.
     Clicking a series card navigates to /series/{slug}/.

Individual Series Page (/series/{slug}/)
     Template: taxonomy-series.php.
     Header: series cover graphic, series name, series blurb.
     Below: all books in the series displayed in volume number order (Book 1, Book 2, etc.).
     Each book entry: cover thumbnail, title, pen name, volume number label ("Book 1"), brief blurb excerpt, purchase link buttons.
     Works correctly when only one book exists in the series.
     Breadcrumb: Home > Series > [Series Name].

3.8 Registration  Sign-Up Page (/signup/)
Template: page-signup.php. Full-width, no sidebar. Managed by the BDMurphy-BookShelf plugin.
     Accessed from: About page sign-up prompt, About page sidebar card, footer sign-up link, and any "Subscribe" calls to action on the site.
     Fields: Email address (required), First name (optional), opt-in confirmation checkbox.
     Opt-in categories: Newsletter, New Book Announcements, Events.
     On submission: stores record in the BDMurphy-BookShelf plugin subscriber table with status = "subscribed". Displays a confirmation message.
     The page includes a brief description of what subscribers receive.
     Shortcode [bookshelf_signup] available for placing the form in other pages or widget areas.
     Registered users can return to this page to update their category preferences.

3.9 Social Sharing Buttons
Social sharing buttons appear at the bottom of individual blog posts and individual book pages only. Not shown on list pages (home, /books/, /blog/, /reviews/, /series/).

Platforms	Facebook, X/Twitter, LinkedIn, WhatsApp, and a "Copy link" button. Additional platforms can be toggled on/off in Appearance > Theme Options > Social Sharing.
URL on book pages	The book's short URL (e.g. authorbdmurphy.com/ph)  not the full canonical URL. Retrieved from the book's stored short slug.
URL on blog posts	The standard WordPress post permalink.
Implementation	Uses the Web Share API where available (modern mobile browsers). Falls back to platform-specific share URLs on desktop. No third-party sharing plugin dependency.
Share counts	Not displayed  avoids third-party API calls and privacy concerns.

3.10 Utility Pages
Privacy policy (/privacy-policy/)	Standard static WordPress Page. Template: page.php or page-no-sidebar.php.
Unsubscribe (/unsubscribe/)	Single email input. Sets subscriber status to "unsubscribed" in the BDMurphy-BookShelf plugin. Accepts HMAC-signed one-click unsubscribe tokens from email links. Template: page-unsubscribe.php.
Contact (/contact/)	Template: page-no-sidebar.php. Fields: Name, Email, Subject, Message. AJAX submission. Honeypot field for spam protection.

4. Design System

4.1 Color Palette
Navy blue #1B3A6B	Primary brand  headers, nav bar, section banners. Customizer-controlled (primary_color).
Slate blue #2E6DA4	Heading text, links, active states. Fixed, derived from primary_color.
Sky blue #4A90D9	Hover states, accent highlights. Fixed.
Warm gold #C8A96E	Decorative accents, active nav underline, dividers. Customizer-controlled (accent_color).
Cream #F5F0E8	Page background. Customizer-controlled via custom-background (default-color: F5F0E8).
Parchment #EDE4D0	Card and sidebar backgrounds, alternating table rows. Fixed.
Body text #2C2C2C	Primary body copy. Fixed.
Mid grey #555555	Secondary text, metadata. Fixed.
Light grey #888888	Placeholder text, disabled states. Fixed.
Active green #2D6A4F	Format toggle active state. Fixed.
Note: Colors output as CSS custom properties: --bdm-navy, --bdm-gold, --bdm-cream, etc. Light mode only  no dark mode.

4.2 Typography
Heading font	Playfair Display, Georgia, serif. Customizer-controlled (heading_font).
Body font	Lato, Calibri, sans-serif. Customizer-controlled (body_font).
Navigation	Lato, Calibri  medium weight, small caps optional. Fixed.
Pull quotes / blurbs	Playfair Display italic. Inherits heading_font.
Short links / code display	Courier New, monospace. Fixed.
Note: Google Fonts loaded via wp_enqueue_style() with display=swap.

4.3 Image Sizes
shelf-thumb  4462px	Book shelf widget covers on home page right column.
blog-thumb  10068px	Blog post list featured image thumbnails.
rev-thumb  5274px	Review page book cover thumbnails.
book-cover  130185px	All books page cover images.
book-page-cover  220310px	Individual book page main cover.
series-card  400280px	Series listing page card graphics.
series-header  1200300px	Individual series page header graphic.
Note: All sizes registered via add_image_size() in functions.php. WordPress generates crops automatically on upload.

4.4 Responsive Breakpoints
? 1200px	Full two-column layouts, full banner, desktop navigation bar.
7681199px	Columns stack to single column. Navigation collapses to hamburger menu.
< 768px	Single column, touch-friendly tap targets (minimum 4444px). Banner scales proportionally.
Note: Sticky nav functions at all breakpoints. On mobile, hamburger menu opens below the sticky nav bar.

5. Plugin: BDMurphy-BookShelf

The BD-BookShelfHelper plugin is documented in a separate specification: BD-BookShelfHelper-Plugin-Specification-v1_0.docx. This section covers the BDMurphy-BookShelf plugin.

5.1 Overview
The BDMurphy-BookShelf plugin handles subscriber sign-up and management, email newsletter creation, AI-assisted newsletter composition, and delivery via Gmail SMTP. It also registers the book shelf sidebar widget on the home page right column and the /signup/ registration page.

5.2 Plugin Identity
Plugin name	BDMurphy-BookShelf
WordPress slug	bdmurphy-bookshelf
Dashboard menu label	BookShelf
Text domain	bdmurphy-bookshelf

5.3 Responsibilities
     Home page book shelf sidebar widget  registered and rendered in the "Home Sidebar" widget area.
     Sign-up page (/signup/)  registration form, opt-in category selection, subscriber storage.
     Subscriber management  subscribed / unsubscribed status, category preferences, audit fields.
     Email newsletter composition  AI-assisted drafting via Gemini API, HTML editor, template selection.
     Email delivery  one at a time via Gmail SMTP using an app-specific password.
     Unsubscribe processing  HMAC-signed one-click tokens and manual /unsubscribe/ form.
     CAN-SPAM compliance  mandatory footer with business address pulled from Theme Options.

5.4 Gmail SMTP Configuration
Email address	Full email address used for sending.
App-specific password	Generated in Google Account > Security. Stored encrypted in wp_options.
Sender display name	Display name, e.g. "B.D. Murphy".
Reply-to address	Can differ from sender address.
AI API key	Gemini API key for AI-assisted newsletter composition. Stored encrypted.
AI link	Used for AI to check and help craft newsletters and emails.
Business information	Pulled automatically from Appearance > Theme Options > Business Information for CAN-SPAM compliance.
Site URL (boilerplate)	Auto-populated from get_bloginfo('url').
SMTP configuration	Configuration screen includes help text and links to Gmail app password setup guide.

5.5 Email Newsletter Composition Workflow
     Author opens BookShelf > New Newsletter.
     Author enters a prompt summary: topic, books to mention, tone, and announcements.
     Plugin calls Gemini API with a system instruction to generate a complete newsletter HTML draft.
     Draft is returned in an HTML email editor. Headers and footers are auto-populated above and below the editor so the author sees the full reader view.
     Author reviews and edits the draft content.
     Author checks "Also publish as blog post"  creates a WordPress post with the same content. This checkbox is ON by default.
     Author clicks "Send Newsletter"  sends one email at a time via Gmail SMTP to all subscribed recipients.
Note: Sending is always manually triggered. There is no automatic or scheduled send.

5.6 Email Template Requirements
     Email template is selectable in BookShelf settings.
     Header: site name / author name and logo.
     Body: composed content with affiliate-coded purchase links.
     Mandatory footer (not editable per send): website URL, one-click unsubscribe link (HMAC-signed token), full business address from Theme Options (CAN-SPAM requirement).

5.7 Subscriber Management
id	Auto-increment primary key.
email	Unique subscriber email address.
first_name	Optional first name.
status	"subscribed" or "unsubscribed"  records are never deleted.
subscribed_categories	Newsletter, Announcements (new books), Events  per-subscriber opt-in flags.
subscribed_at	Timestamp of original opt-in.
unsubscribed_at	Timestamp of unsubscribe (null if still subscribed).
ip_address	IP address at sign-up for audit purposes.
One-click unsubscribe: HMAC-signed token in every email link. Clicking the link sets status = "unsubscribed" immediately, no form required. Satisfies Gmail and Yahoo delivery requirements. The /unsubscribe/ page also accepts manual email entry as a fallback.

5.8 Plugin Settings & Admin Dashboard
The plugin adds a top-level menu item to the WordPress dashboard called "BookShelf". Submenus provide access to all features.

BookShelf > Settings	Gmail credentials (email address, app-specific password), sender display name, reply-to address, Gemini API key, email template selection. Business information is pulled from Theme Options and displayed read-only here.
BookShelf > New Newsletter	AI-assisted email composition screen.
BookShelf > Sent Newsletters	Log of previously sent newsletters with subject, sent date, and recipient count.
BookShelf > Subscribers	Subscriber list with status, category preferences, and sign-up date.
BookShelf > About	Plugin version, author credit, Buy Me a Coffee link, PayPal donate link.

6. Database Schema (Overview)

6.1 BD-BookShelfHelper Tables
Full detail in the BD-BookShelfHelper Plugin Specification, Section 11.
bd_books	Core book record (id, slug, pen_name_id, series_id, volume_number, asin, isbn, publish_date, sort_order, created_at).
bd_book_meta	Per-language content (book_id, language_code, title, blurb, preview_excerpt, pull_quotes).
bd_book_covers	Cover images per language (book_id, language_code, attachment_id).
bd_series	Series definitions (id, name, slug, cover_attachment_id, header_attachment_id, blurb, display_order, created_at).
bd_pen_names	Pen name list (id, pen_name, notes, active, created_at).
bd_retailers	Retailer definitions (id, name, url_pattern, affiliate_param, formats_supported).
bd_book_links	Purchase links (book_id, retailer_id, format, raw_url, affiliate_url, last_verified).
bd_reviews	Review records (id, book_id, comment_text, synopsis, source_name, source_url, display_order).
bd_ratings	Scraped ratings cache (book_id, source [amazon|goodreads], rating, review_count, last_updated).
bd_review_shortlinks	Review short links (id, book_id, site_code, slug, destination_url, status, created_at, activated_at).

6.2 BDMurphy-BookShelf Tables
bd_subscribers	Subscriber list (id, email, first_name, status, subscribed_categories, subscribed_at, unsubscribed_at, ip_address).
bd_newsletters	Sent newsletter log (id, subject, body_html, sent_at, recipient_count).

7. Design Decisions  Answered

All design decisions have been resolved. This section records each decision and its specification impact for developer reference.

Question	Answer	Spec Impact
Child theme support?	No  customisation via Customizer and Theme Options only.	All paths use get_template_directory_uri(). No child theme infrastructure needed.
Dark mode?	No dark mode support.	Light mode only confirmed. Parchment palette stands.
Sign-up form  popup or page?	Dedicated page (/signup/) accessed from About menu and footer.	Section 3.8. About page and footer include sign-up prompt. Shortcode [bookshelf_signup] also available.
Visitor-submitted reviews?	No  admin-entered only. Reviews come from Amazon, Goodreads, etc.	Admin-only entry. No moderation tooling needed.
Blog post trigger email newsletter?	No  future separate AI-driven plugin (blog ? email / social, not a copy).	Section 8.4 notes the planned extension and reserves a WordPress action hook.
Social sharing buttons?	Yes  bottom of blog posts and book pages.	Section 3.9. Facebook, X/Twitter, LinkedIn, WhatsApp, copy-link. Book pages share the short URL.
Series page?	Yes  full series system with /series/ listing and /series/{slug}/ detail pages.	Section 3.7. BD-BookShelfHelper series management. Series nav item conditional on series existing.
Affiliate IDs?	User adds IDs as they sign up. Applied whenever available.	Links display without affiliate code until an ID is configured for that retailer.
CAN-SPAM mailing address?	User configures business information (name, address, phone) in Theme Options.	Business info fields in Section 2.5. BDMurphy-BookShelf plugin pulls them into every email footer.
One-click unsubscribe?	Yes  HMAC-signed token in email link.	Section 5.7. Token-based unsubscribe confirmed as standard.
Goodreads Author ID?	ID: 30469651 (goodreads.com/author/show/30469651.B_D_Murphy)	Pre-populated in BD-BookShelfHelper sample data.
Multiple authors / pen names?	One author, one bio. Up to 10 pen names. Each book shows the pen name it was published under.	BD-BookShelfHelper pen name management (Plugin Spec Section 4). About page bio is for the author, not per pen name.
Series sort order?	Volume number field controls both display order and the "Book [N]" label.	Volume number in bd_books. Sorts books within a series on all series pages.
Email plugin name?	The BD-SimpleEmail plugin is merged into BDMurphy-BookShelf. Email features are part of that plugin.	All references to "SimpleEmail" or "BD-SimpleEmail" in this document now refer to the BDMurphy-BookShelf plugin.

8. Implementation Notes

8.1 WordPress Architecture
     "book" custom post type registered by BD-BookShelfHelper. The theme queries it but does not register it.
     "series" registered as a custom taxonomy by BD-BookShelfHelper, attached to the book CPT.
     Book page short links and review short links registered as WordPress rewrite rules via add_rewrite_rule(). Slugs stored as post meta and in bd_review_shortlinks.
     Internationalisation: theme uses __() and _e() with text domain "bd-murphy". load_theme_textdomain() in functions.php. .pot generated via WP-CLI i18n make-pot.
     Scheduled tasks via WP-Cron: Goodreads widget refresh (daily), Amazon rating scrape (every 6 hours), review link activation scan (daily).
     All CSS and JS enqueued via wp_enqueue_style() and wp_enqueue_script() with correct handles, dependencies, and version strings.

8.2 Security
     Gmail app password and Gemini API key stored encrypted (openssl_encrypt), never plain text.
     Unsubscribe tokens: HMAC-signed (hash_hmac)  never bare email addresses in URLs.
     All output escaped with esc_html(), esc_url(), esc_attr(). All input sanitized on save.
     Affiliate codes applied server-side only.
     Contact form honeypot field for spam protection.

8.3 Sample Data
     "Pandemic Hacker" by B.D. Murphy  placeholder cover, sample reviews, ratings, blurb.
     Pre-reserved review short link slugs: phrA, phrG, phrB, phrK, phrP, phrL.
     All five retailer purchase link placeholders pre-configured for Pandemic Hacker.
     Three sample blog posts.
     Goodreads Author ID 30469651 pre-populated in BD-BookShelfHelper settings.
     Pen name "B.D. Murphy" pre-configured as the default active pen name.
Note: A "Clear sample data" button in Appearance > Setup Wizard removes all sample content.

8.4 Planned Extension  Blog to Social / Email Plugin
A future AI-driven plugin will take a published blog post and generate distinct email newsletter content and social media posts  not a copy of the blog, but an AI-transformed version appropriate for each channel.
     Scope: out of scope for the current build. No implementation required now.
     Hook point reserved: the theme and BD-BookShelfHelper fire do_action('bdm_post_published', $post_id) when a book or blog post is published. The future plugin attaches to this hook without requiring changes to the theme or existing plugins.
     The BDMurphy-BookShelf plugin (current) handles one-way manual email composition only. The future plugin is separate.

8.5 Required Theme Support Declarations
All required add_theme_support() calls in functions.php:

title-tag	Lets WordPress manage the <title> element. Not hard-coded in header.php.
custom-logo	array( 'width' => 250, 'height' => 250, 'flex-width' => true, 'flex-height' => true )
custom-header	array( 'default-image' => get_template_directory_uri().'/assets/Reading_through_time.png', 'width' => 1200, 'height' => 250, 'flex-height' => false )
custom-background	array( 'default-color' => 'F5F0E8' )
post-thumbnails	No args. Required for featured images.
html5	array( 'search-form', 'comment-form', 'comment-list', 'gallery', 'caption', 'script', 'style' )
automatic-feed-links	No args. Adds RSS/Atom links to head.
wp-block-styles	No args. Applies default Gutenberg block styles.
editor-style	add_editor_style('assets/editor-style.css').
add_image_size	shelf-thumb 4462 (crop), blog-thumb 10068 (crop), rev-thumb 5274 (crop), book-cover 130185 (crop), book-page-cover 220310 (crop), series-card 400280 (crop), series-header 1200300 (crop).

8.6 Template File Structure
style.css	Theme header: Theme Name: BDMurphy-Bookshelf, Author, Version, Text Domain: bd-murphy.
functions.php	add_theme_support(), register_nav_menus(), register_sidebar(), wp_enqueue_scripts, Customizer panels, Theme Options, bdm_post_published action hook.
header.php	wp_head(), banner image, sticky nav, body_class().
footer.php	Footer three-zone layout, sign-up prompt, wp_footer().
front-page.php	Home page two-column layout.
sidebar-home.php	Home right column  book shelf widget area.
archive.php / home.php	Blog post list.
archive-book.php	All books page.
single-book.php	Individual book page (series display and social sharing).
archive-series.php	Series listing page (/series/).
taxonomy-series.php	Individual series page (/series/{slug}/).
page.php	Default page template with sidebar.
page-full-width.php	Full width. Template Name: Full Width.
page-no-sidebar.php	Single column. Template Name: No Sidebar.
page-about.php	About page. Template Name: About.
page-reviews.php	Reviews grid. Template Name: Reviews.
page-unsubscribe.php	Unsubscribe form. Template Name: Unsubscribe.
page-signup.php	Sign-up page. Template Name: Sign Up.
404.php	404 error page.
search.php	Search results.

8.7 Required Template Tag Usage
     body_class() on body tag  plugin hooks and admin bar CSS offset.
     post_class() on post/book wrapper divs  plugin hooks and state classes.
     wp_head() immediately before closing </head>  required for all plugins.
     wp_footer() immediately before closing </body>  required for all plugins.
     the_custom_logo() for logo output.
     get_header_image() for banner image output.
     wp_nav_menu(['theme_location' => 'primary']) for main nav.
     wp_nav_menu(['theme_location' => 'footer']) for footer links.
     dynamic_sidebar('home-sidebar') for the book shelf widget area.
     do_action('bdm_post_published', $post_id) fired on book and blog post publish.

End of BDMurphy BookShelf System Specification v2.0
Note: For the BD-BookShelfHelper plugin full specification, see: BD-BookShelfHelper-Plugin-Specification-v1_0.docx
