` instead of `
`
- - Example transformation:
- ```markdown
- ```mermaid
- graph TD
- A[Start] --> B[Process]
- ```
- ```
- becomes:
- ```html
-
- graph TD
- A[Start] --> B[Process]
-
- ```
-
-17. **Test Mermaid Rendering**
- - Create test markdown file with sample mermaid diagrams (flowcharts, sequence diagrams, class diagrams)
- - Verify diagrams render correctly in generated site
- - Test different mermaid diagram types
- - Validate accessibility and responsive design
-
-18. **Document Mermaid Usage**
- - Add documentation for content authors on how to use mermaid in markdown
- - Provide examples of different diagram types
- - Update CLAUDE.md with mermaid support
-
-**Week 7: Testing and Deployment**
-
-19. **Comprehensive Testing**
- - All 113 newsletters render correctly
- - All podcast episodes render correctly
- - Components produce identical HTML
- - GitLab CI passes (macOS + Ubuntu)
- - Performance within 10% baseline
-
-20. **Expand Test Coverage**
- - Component unit tests
- - Concurrency safety tests
- - Integration tests
- - Mermaid rendering tests
- - Target: >50% coverage (from ~5%)
-
-21. **Production Deployment**
- - Deploy to staging
- - Byte-for-byte HTML comparison (excluding mermaid diagrams - visual verification)
- - Visual regression testing
- - Test mermaid diagrams in production environment
- - Deploy to production
-
-**Deliverables:**
-- [ ] All 17 subrepos upgraded to Swift 6
-- [ ] Publish ecosystem packages (8) support swift-markdown
-- [ ] BrightDigit packages (7) upgraded to Swift 6
-- [ ] Forked plugins (2) upgraded to Swift 6
-- [ ] brightdigit.com using components exclusively
-- [ ] Zero direct Plot HTML creation in codebase
-- [ ] Zero concurrency warnings across all 17 subrepos
-- [ ] Testimonial data race fixed
-- [ ] All Sendable conformances added
-- [ ] Mermaid diagram support integrated (client-side mermaid.js)
-- [ ] Mermaid diagrams render correctly in test content
-- [ ] Test coverage >50%
-- [ ] All subrepo updates pushed to upstream repos
-- [ ] Production deployment successful with mermaid support
-
----
-
-### Phase 4: Publishing Infrastructure (3-4 weeks)
-
-**Objective:** Build an open source Swift package that integrates into the BrightDigit.com publishing pipeline to deliver content across newsletter (Buttondown) and social media (Buffer) channels — without storing any audience data in the repository.
-
-This phase depends on Phase 2 (swift-openapi-generator toolchain) and Phase 3 (Swift 6 compliance).
-
-#### Constraints
-
-- **Open source repo:** No subscriber emails or audience data in the repo. All credentials are environment variables. All audience list management is delegated to the platform.
-- **Linux compatibility:** All HTTP clients use `ClientTransport` from `swift-openapi-runtime`, allowing the transport to be swapped per platform:
- ```swift
- // Linux (CI/CD, server-side Swift):
- let transport: any ClientTransport = AsyncHTTPClientTransport()
- // Apple platforms:
- let transport: any ClientTransport = URLSessionTransport()
- ```
-- **General-purpose:** Multi-channel publishing. Social posts go to Buffer, which fans out to X/Twitter, LinkedIn, Mastodon, and others from a single API call.
-
-#### New Source Modules
-
-These are added to `Sources/` in the monorepo (not git-subrepos — they are new code local to this project):
-
-```
-Sources/
- PublishKit/ # Core orchestrator + protocol definitions
- ButtondownKit/ # Newsletter: Buttondown REST client (swift-openapi-generator)
- MailgunKit/ # Newsletter: sending-only transport (no list management)
- BufferKit/ # Social: handwritten GraphQL client (ClientTransport, Codable)
-```
-
-#### Newsletter Transport: Buttondown
-
-**Protocol architecture** (exact shapes TBD during implementation):
-
-- `SubscriberListProvider` — fetching/managing the list of recipients
-- `NewsletterSender` — delivering a composed issue to recipients
-
-This split allows Mailgun (sender-only) to be composed with a separate list provider without a full platform swap.
-
-**Why Buttondown:** Newsletter-native API. Sending an issue is two REST calls:
-```
-POST /emails → create draft (body is markdown string)
-POST /emails/{id}/send-draft → send to all subscribers
-```
-Subscriber management, unsubscribe links, bounce handling, and CAN-SPAM compliance are all managed by Buttondown. **Cost:** $9/month.
-
-**Code generation:** swift-openapi-generator from the official Buttondown OpenAPI 3.0.2 spec at [github.com/buttondown/openapi](https://github.com/buttondown/openapi).
-
-**Why not Mailgun as a complete solution:** Mailgun is a transactional email API — it does not manage subscribers. Owning the subscriber list means storing ~400 email addresses, which has no safe home in an open source repo. Mailgun remains a valid `NewsletterSender` implementation when paired with a separate list provider.
-
-#### Social Transport: Buffer
-
-Buffer publishes to X/Twitter, LinkedIn, Mastodon, Instagram, Threads, Bluesky, and more from a single GraphQL mutation — no per-platform OAuth or rate-limit handling required.
-
-**Implementation:** `BufferTransport` wraps a `ClientTransport` instance. Encodes the GraphQL mutation as `{"query": "...", "variables": {...}}` and decodes the response with `Codable`. No Apollo, no code generation dependency — fully Linux-compatible.
-
-```graphql
-mutation CreatePost {
- createPost(input: {
- text: "...",
- channelId: "...",
- schedulingType: automatic,
- mode: shareNow # or addToQueue for scheduling
- }) {
- ... on PostActionSuccess { post { id } }
- ... on MutationError { message }
- }
-}
-```
-
-#### Credential Model
-
-| Variable | Used By | Never Stored In |
-|---|---|---|
-| `BUTTONDOWN_API_KEY` | ButtondownKit | Repo, subscriber list |
-| `BUFFER_API_TOKEN` | BufferKit | Repo, audience data |
-
-#### Week 1-2: Core Protocol Design + ButtondownKit
-
-1. Define `SubscriberListProvider` and `NewsletterSender` protocol shapes in PublishKit
-2. Run swift-openapi-generator against Buttondown's OpenAPI 3.0.2 spec
-3. Implement `ButtondownTransport` conforming to both protocols
-4. Wire up `ClientTransport` (AsyncHTTPClientTransport on Linux, URLSessionTransport on Apple)
-5. Test: create draft, send draft, verify delivery
-
-#### Week 3: BufferKit + MailgunKit
-
-6. Implement `BufferTransport` — plain HTTP POST to GraphQL endpoint
-7. Encode mutation as JSON body; decode response with Codable
-8. Implement `MailgunTransport` (sender-only; list provider injected separately)
-9. Test: publish a social post through Buffer; test Mailgun send path in isolation
-
-#### Week 4: PublishKit Integration + Swift 6 Compliance
-
-10. Implement `Publisher` orchestrator in PublishKit
-11. Integrate with BrightDigit.com publishing pipeline (Publish plugin entry point or CLI subcommand)
-12. Ensure all modules pass Swift 6 strict concurrency checks
-13. Validate Linux builds in CI (Ubuntu, AsyncHTTPClientTransport)
-14. End-to-end test: publish a real newsletter draft and a real social post
-
-#### Decision Summary
-
-| Decision | Choice | Reason |
-|---|---|---|
-| Newsletter platform | Buttondown | Open source constraint eliminates subscriber ownership; REST + official OpenAPI spec; markdown-native |
-| Social platform | Buffer | Single API for all networks; GraphQL early access available; no per-platform integration |
-| Newsletter architecture | Split `SubscriberListProvider` + `NewsletterSender` | Mailgun = sender only; separation allows composition with any list provider |
-| Newsletter code gen | swift-openapi-generator | Official OpenAPI 3.0.2 spec from Buttondown |
-| Social code gen | None | Buffer API is GraphQL; handwritten Codable client requires no code gen dependency |
-| HTTP transport abstraction | `ClientTransport` (swift-openapi-runtime) | Swap `AsyncHTTPClientTransport` (Linux) / `URLSessionTransport` (Apple) — applies to all clients |
-| Subscriber storage | None (Buttondown-managed) | Cannot store audience data in open source repo |
-| Integration target | BrightDigit.com SSG (Publish, migration pending) | Tool is a publishing pipeline plugin, not a standalone CLI |
-
-**Deliverables:**
-- [ ] PublishKit protocols defined (`SubscriberListProvider`, `NewsletterSender`)
-- [ ] ButtondownKit generated from official OpenAPI 3.0.2 spec
-- [ ] BufferKit handwritten GraphQL client, Linux-compatible
-- [ ] MailgunKit sender-only transport
-- [ ] All modules Swift 6 strict concurrency compliant
-- [ ] All modules build on Linux (Ubuntu) via AsyncHTTPClientTransport
-- [ ] Integration with BrightDigit.com publishing pipeline
-- [ ] Credentials sourced from environment variables only
-
----
-
-### Video Podcasts (issue #32)
-
-**Scope:** TBD — add video podcast support to the BrightDigit podcast section. Likely builds on the YouTube integration established in Phase 2 and the component system from Phase 3.
-
-**Candidate work items (to be defined):**
-- Support video-first podcast episodes (YouTube video as primary media)
-- Display embedded video player in episode pages alongside audio player
-- Update podcast RSS feed generation to include video enclosures where applicable
-- Update `ContributeYouTube` / `BrightDigitPodcast` to distinguish video vs audio episodes
-
-**Dependencies:** Phase 2 (#37) for YouTube client, Phase 3 (#38) for component system.
-
----
-
-### AI-CITE Content Optimization (parallel, ongoing — branch: ai-cite-optimization, PR #39)
-
-**Scope:** Optimize BrightDigit article and tutorial content to be cited by AI systems (ChatGPT, Google AI Overview) using the AI-CITE framework (Answer-first, Intent-matched headings, Clear structure, Indexed schema, Trusted sources, Exclusive POV). Based on Jesse Schoberg's MicroConf Europe 2025 methodology.
-
-**Framework:** AI-CITE — each element maps to a content transformation:
-- **A (Answer-first):** Lead with the direct answer in the first paragraph
-- **I (Intent-matched headings):** Rewrite headings as search queries (e.g., "Three Ways to Mock Swift Dependencies")
-- **C (Clear structure):** Replace dense prose with tables, numbered lists, decision guides, TLDR sections
-- **I (Indexed schema):** Add FAQPage, HowTo, and Article JSON-LD structured data
-- **T (Trusted sources):** Link to Apple docs, WWDC sessions, Swift.org, official repos
-- **E (Exclusive POV):** Create branded frameworks/methodologies unique to BrightDigit
-
-**Target Success Rate:** 60% of priority articles get AI mentions within 1 week of optimization.
-
-**Reference Documentation:** `.claude/ai-cite-optimization/`
-- [`00-README.md`](./ai-cite-optimization/00-README.md) — framework overview and quick links
-- [`ai-cite-audit.md`](./ai-cite-optimization/ai-cite-audit.md) — top 10 "money articles" identified for optimization
-- [`implementation-summary.md`](./ai-cite-optimization/implementation-summary.md) — before/after metrics
-- [`schema-implementation-plan.md`](./ai-cite-optimization/schema-implementation-plan.md) — JSON-LD structured data design
-- [`VALIDATION.md`](./ai-cite-optimization/VALIDATION.md) — testing and validation approach
-- [`complete-status.md`](./ai-cite-optimization/complete-status.md) — sprint status tracker
-- [`issues/INDEX.md`](./ai-cite-optimization/issues/INDEX.md) — all 10 GitHub issues
-
-**Planned Content Files (to be added in subsequent PRs):**
-- `Content/articles/dependency-management-swift.md` — rewritten with AI-CITE structure (answer-first, FAQ section, comparison tables, structured code examples)
-- `Content/articles/mise-implementation-guide.md` — new comprehensive Mise adoption guide (~4,980 lines, internal reference article)
-- `Content/tutorials/mise-setup-guide.md` — new public-facing Mise setup tutorial
-- `Content/tutorials/project-setup-guide.md` — new project setup tutorial (draft)
-- `Content/tutorials/why-mistkit.md` — new MistKit explanation (draft)
-
-**Sprint Plan (from `complete-status.md`):**
-- Sprint 1 — FAQ/HowTo schema, Mise setup guide optimization (issues #21, #22, #23)
-- Sprint 2 — Baseline testing and validation (issue #26)
-- Sprint 3 — Remaining 10 priority articles (issue #28)
-- Sprint 4+ — YouTube video strategy and unique frameworks (issues #24, #25)
-
-**GitHub Issues:** #21–#30 (tracked in `.claude/ai-cite-optimization/issues/`)
-
-**Dependencies:** None — runs parallel to all technical phases. Schema markup (JSON-LD) from the Indexed element may benefit from Phase 3's component system if `PiHTMLFactory` is updated to inject structured data into page `` automatically.
-
----
-
-### Appendix: Early Concurrency Analysis (Pre-Phase 2)
-
-**Critical Files for Modernization:**
-
-**1. ContributeMailchimp/Prch.APIClient.Newsletter.swift**
-- Convert `campaigns(fromRequest:) throws` to `async throws`
-- Replace `requestSync` with Prch's native async `request()` API
-- Update all callers to use async/await
-
-**2. ContributeYouTube/Prch.APIClient.Podcast.swift**
-- **Most Complex Migration** - Replace DispatchSemaphore + mutable closure captures
-- Convert to `withThrowingTaskGroup` for parallel video fetching
-- Lines 14-26: Eliminate semaphore synchronization
-- Lines 33-62: Replace DispatchGroup with TaskGroup
-
-**3. BrightDigitArgs/Import/Mailchimp.swift**
-- Line 47: Convert force-try NSRegularExpression to lazy closure
-- Lines 108-120: Convert `run()` to `async throws`
-- Update ArgumentParser command to use async
-
-**4. Error Handling Modernization**
-
-Force-try statements to eliminate:
-- `Mailchimp.swift:47` - NSRegularExpression initialization
-- `YAMLStringFix.swift:6` - NSRegularExpression initialization
-- `String.swift:4` - NSRegularExpression initialization
-
-Replace with lazy static closures or throwing getters.
-
-**5. Error Suppression**
-- `RSSContent.swift:21` - Replace `try?` with explicit error handling and logging
-
-**Deliverables:**
-- [ ] All `requestSync` usage eliminated
-- [ ] All DispatchSemaphore usage replaced with async/await
-- [ ] All DispatchGroup usage replaced with TaskGroup
-- [ ] Force-try statements replaced with proper error handling
-- [ ] ArgumentParser commands use async run() methods
-
-### Appendix: Early Strict Concurrency Analysis (Pre-Phase 3)
-
-**Critical Issue 1: Mutable Global State**
-
-**File:** `Sources/BrightDigitSite/Testimonial.swift`
-
-**Current Code (Lines 5, 19-20):**
-```swift
-static var lastID = 0 // ❌ Data race
-internal init(id: Int? = nil, ...) {
- self.id = id ?? (Self.lastID + 1)
- Self.lastID += 1 // ❌ Not thread-safe
-}
-```
-
-**Recommended Solution:** Remove auto-increment, use explicit IDs
-- All testimonials already have static definitions with IDs
-- Make `id` parameter required (remove default `nil`)
-- Remove `static var lastID`
-- **Risk:** LOW - straightforward refactor
-- **Effort:** 1-2 hours
-
-**Critical Issue 2: URLSession Sendable Compliance**
-
-**Files:** `Mailchimp.swift:109`, `YouTubeContent.swift:20`
-- Verify Prch.Client is Sendable
-- Verify API types (YouTube.API, Mailchimp.API) are Sendable
-- Add explicit type annotations
-
-**Critical Issue 3: Implicit Sendable Conformances**
-
-Types needing explicit Sendable conformance:
-- `Newsletter.Source` (ContributeMailchimp)
-- `YouTubeContent.Source` (ContributeYouTube)
-- `RSSContent.Source` (ContributeRSS)
-- `BrightDigitPodcast.Source`
-
-**Deliverables:**
-- [ ] Testimonial.lastID data race resolved
-- [ ] All Sendable conformances added
-- [ ] URLSession usage verified thread-safe
-- [ ] Zero concurrency warnings in Xcode
-- [ ] Swift 6 strict mode enabled and passing
-
-### Appendix: Early Testing and Validation Analysis (Pre-Phase 3)
-
-**Current Test Coverage:** ~5% (1 test file: `StringTests.swift`)
-
-**Required Test Expansion:**
-
-1. **Concurrency Safety Tests**
- - Testimonial ID thread safety
- - Concurrent video fetching
- - Concurrent campaign fetching
-
-2. **Migration Validation Tests**
- - Generate site and compare with baseline (byte-for-byte)
- - Verify async version produces same results as sync
-
-3. **Integration Tests**
- - Full newsletter import flow
- - Full podcast import flow
- - Site generation pipeline
- - GitLab CI compatibility
-
-**Performance Benchmarking:**
-
-| Operation | Target | Measurement |
-|-----------|--------|-------------|
-| Newsletter import | Within 10% of baseline | Time to import 113 newsletters |
-| Podcast import | Within 10% of baseline | Time to fetch YouTube playlist |
-| Site generation | Within 10% of baseline | Time to run publish command |
-| Memory usage | Within 20% of baseline | Peak memory during build |
-
-**Deliverables:**
-- [ ] Test coverage expanded to >50%
-- [ ] All concurrency-critical paths tested
-- [ ] CI/CD pipeline passing on all platforms
-- [ ] Performance benchmarks within acceptable range
-- [ ] Deployment to staging validated
-- [ ] Production deployment checklist complete
-
----
-
-## Critical Code Changes Required
-
-### File-by-File Migration Guide
-
-#### 1. Package.swift (CRITICAL)
-**Changes:**
-- Line 1: Update to `// swift-tools-version: 6.0`
-- Lines 11-12: Update platform to `.macOS(.v13)`
-- Add `swiftSettings: [.enableExperimentalFeature("StrictConcurrency")]` to all targets
-- **Estimated Effort:** 2-3 hours (includes testing)
-
-#### 2. Testimonial.swift
-**Changes:**
-- Line 5: Remove `static var lastID = 0`
-- Lines 19-20: Remove auto-increment logic
-- Line 18: Make `id` parameter required
-- **Risk/Complexity:** LOW/LOW
-- **Estimated Effort:** 1-2 hours
-
-#### 3. Prch.APIClient.Podcast.swift (HIGHEST COMPLEXITY)
-**Changes:**
-- Lines 14-26: Convert to async/await
-- Lines 28-75: Rewrite using `withThrowingTaskGroup`
-- Lines 33-62: Replace DispatchGroup with TaskGroup
-- Line 53: Remove mutable array with closure mutation
-- **Risk/Complexity:** HIGH/MEDIUM
-- **Estimated Effort:** 1-2 days
-
-#### 4. Prch.APIClient.Newsletter.swift
-**Changes:**
-- Lines 14-21: Convert `campaigns` to async
-- Lines 23-30: Convert `htmlFromCampaign` to async
-- Lines 32-41: Update `source` to async
-- Lines 43-52: Update `newsletters` to async with TaskGroup
-- **Risk/Complexity:** MEDIUM/LOW
-- **Estimated Effort:** 4-6 hours
-
-#### 5. Mailchimp.swift
-**Changes:**
-- Line 47: Convert force-try regex to lazy closure
-- Lines 108-120: Convert `run()` to `async throws`
-- **Risk/Complexity:** MEDIUM/LOW
-- **Estimated Effort:** 3-4 hours
-
-#### 6. YouTubeContent.swift
-**Changes:**
-- Lines 17-57: Convert to async
-- Line 20: Ensure URLSession.shared Sendable compliance
-- **Risk/Complexity:** LOW/LOW
-- **Estimated Effort:** 2-3 hours
-
-#### 7. YAMLStringFix.swift
-**Changes:**
-- Lines 6-9: Convert force-try to lazy closure
-- **Risk/Complexity:** LOW/LOW
-- **Estimated Effort:** 30 minutes
-
-#### 8. ContributeRSS/String.swift
-**Changes:**
-- Line 4: Convert force-try to lazy closure
-- **Risk/Complexity:** LOW/LOW
-- **Estimated Effort:** 30 minutes
-
-#### 9. RSSContent.swift
-**Changes:**
-- Lines 19-22: Replace try? with do-catch and logging
-- **Risk/Complexity:** LOW/LOW
-- **Estimated Effort:** 1 hour
-
----
-
-## Risk Assessment
-
-### Breaking Changes Impact
-
-**High-Risk Changes:**
-
-1. **Async/Await Conversion** (HIGH IMPACT)
- - Impact: Import commands become async
- - Mitigation: ArgumentParser supports async commands natively
- - Likelihood: LOW | Severity: MEDIUM
-
-2. **Dependency Version Updates** (MEDIUM IMPACT)
- - Impact: Breaking API changes possible
- - Mitigation: Review changelogs, create compatibility layer if needed
- - Likelihood: MEDIUM | Severity: HIGH
-
-3. **Platform Requirement Increase** (macOS 13+)
- - Impact: CI/CD runners, developer machines
- - Mitigation: Verify GitLab runner macOS version
- - Likelihood: MEDIUM | Severity: LOW
-
-### Deployment Risks
-
-| Risk | Likelihood | Impact | Priority | Mitigation |
-|------|-----------|--------|----------|------------|
-| Site generation produces different output | LOW | HIGH | P1 | Byte-for-byte comparison, staging deploy |
-| Import commands fail silently | MEDIUM | HIGH | P1 | Expand error handling, logging |
-| CI/CD pipeline breaks | LOW | HIGH | P1 | Test in feature branch |
-| Performance regression | LOW | MEDIUM | P2 | Benchmark before/after |
-| Ubuntu build fails | MEDIUM | MEDIUM | P2 | Test early, update Docker image |
-
-### Rollback Strategy
-
-**Rollback Triggers:**
-1. Site generation produces incorrect output
-2. Import commands fail to fetch new content
-3. CI/CD pipeline cannot deploy
-4. Performance degrades >25%
-5. Critical dependency incompatibility discovered
-
-**Rollback Procedure:**
-```bash
-# Git-based rollback
-git revert
-git push origin main
-
-# Artifact-based rollback
-cp brightdigitwg-Darwin-arm64.backup brightdigitwg-Darwin-arm64
-netlify deploy --site $NETLIFY_PRODUCTION_SITE_ID --prod
-```
-
-**Rollback SLA:** <70 minutes from detection to recovery
-
----
-
-## Success Metrics
-
-### Compilation Metrics
-- [ ] Zero errors with Swift 6 language mode
-- [ ] Zero concurrency warnings
-- [ ] Zero data race safety errors
-- [ ] All targets compile successfully
-- [ ] Tests pass on macOS and Linux
-
-### Runtime Metrics
-- [ ] Newsletter import produces identical markdown
-- [ ] Podcast import produces identical markdown
-- [ ] Site generation produces identical HTML
-- [ ] All 113 existing newsletters load correctly
-- [ ] All existing podcast episodes load correctly
-- [ ] GitLab CI content automation succeeds
-
-### Performance Validation
-
-| Operation | Baseline (Swift 5.8) | Target (Swift 6) |
-|-----------|---------------------|------------------|
-| Import 113 newsletters | TBD | ≤110% baseline |
-| Fetch YouTube playlist | TBD | ≤110% baseline |
-| Generate full site | TBD | ≤110% baseline |
-| Memory peak | TBD | ≤120% baseline |
-
-### Quality Metrics
-- Test coverage: >25% (from current ~5%)
-- Concurrency test coverage: 100% of concurrent code paths
-- Zero force-try statements (except truly infallible operations)
-
----
-
-## Open Questions
-
-### Technical Decisions Requiring Investigation
-
-**1. SwiftTube Package Strategy**
-- **Decision: SwiftTube is owned by BrightDigit — create a new branch for Swift 6 migration (no fork needed)**
-- No upstream wait required; we control the repo and will push changes directly via `git subrepo push`
-
-**2. Publish Framework Version**
-- Question: Stay on 0.9.0 or upgrade to latest main?
-- **Investigation Needed: Document the actual differences between 0.9.0 and latest main before deciding**
-- Recommendation: Stay on 0.9.0 pending changelog review (Swift 6 compatible, proven stable)
-
-**3. MarkdownGenerator Replacement**
-- **Decision: Migrate to [swiftlang/swift-markdown](https://github.com/swiftlang/swift-markdown) (Apple's official parser)**
-- Ink is no longer an option; swift-markdown is the designated replacement per Phase 1 plan
-
-**4. macOS Version Requirement**
-- **Decision: Require macOS 13+ — drop macOS 12 support (don't care)**
-- Swift 6 officially requires macOS 13+; no investigation needed
-
-**5. Testing Strategy**
-- **Decision: Target 25% test coverage overall**
-- Current: ~5% | Target: 25% (revised down from original >50% proposal)
-
-**6. Deployment Strategy**
-- **Decision: Parallel module-by-module work — a lot of work can be done simultaneously**
-- Modules can be migrated in parallel across subrepos; not strictly big-bang
-
-**7. Content Validation**
-- **Decision: Use automated HTML diffing to validate 113+ newsletters and episodes**
-- Manual spot-checking and visual regression testing are not required
-
-**8. Contribute Package Ownership**
-- **Decision: BrightDigit is the maintainer — we will release Contribute 1.0.0**
-- No external coordination needed; release criteria to be defined internally
-
-**9. Publishing Protocol Shapes**
-- Question: What are the exact method signatures for `SubscriberListProvider` and `NewsletterSender`?
-- Context: PRD documents architectural intent; final API TBD during Phase 4 implementation
-- Investigation Needed: Buttondown API capabilities, composability with Mailgun
-- Decision Maker: Technical Lead
-- Deadline: Phase 4 Week 1
-
-**10. Buffer GraphQL Schema Stability**
-- Question: Is the Buffer GraphQL API (early access) stable enough for production use?
-- Context: Buffer's GraphQL API is labeled "early access" — schema may change
-- Investigation Needed: Buffer API changelog, breaking-change policy, fallback to REST v1
-- Decision Maker: Technical Lead
-- Deadline: Phase 4 Week 1
-
-**11. Publishing Pipeline Integration Point**
-- Question: Does the publishing tool integrate as a Publish plugin, a CLI subcommand, or a standalone binary?
-- Options: Publish plugin (inline with site generation), new `publish` subcommand in BrightDigitArgs, or separate tool
-- Context: The SSG itself is being migrated (brightdigit/brightdigit.com#31); integration point may shift
-- Decision Maker: Technical Lead
-- Deadline: Phase 4 Week 1
-
----
-
-## Critical Files for Implementation
-
-Based on analysis, the most critical files requiring changes:
-
-1. **`Package.swift`**
- - Controls entire project compilation environment
- - Must be updated first
- - Priority: CRITICAL
-
-2. **`Sources/ContributeYouTube/Prch.APIClient.Podcast.swift`**
- - Most complex concurrency violation (DispatchSemaphore + mutable captures + DispatchGroup)
- - Core podcast import functionality
- - Priority: CRITICAL - Highest technical complexity
-
-3. **`Sources/ContributeMailchimp/Prch.APIClient.Newsletter.swift`**
- - Newsletter import synchronous wrapper
- - Production automation dependency
- - Priority: CRITICAL
-
-4. **`Sources/BrightDigitSite/Testimonial.swift`**
- - Textbook mutable global state data race
- - Simple but critical for strict concurrency
- - Priority: HIGH
-
-5. **`Sources/BrightDigitArgs/Import/Mailchimp.swift`**
- - CLI integration, force-try regex
- - Entry point for automation
- - Priority: HIGH
-
----
-
-## Summary
-
-This PRD documents a comprehensive modernization of the BrightDigit static site generator infrastructure through three sequential phases:
-
-### Phase 1: Monorepo Consolidation (3-4 weeks)
-- Consolidate 17 external packages into monorepo using git-subrepo
-- Organize into Packages/Publish/ (8), Packages/BrightDigit/ (7), Packages/Plugins/ (2)
-- Fork YoutubePublishPlugin and ReadingTimePublishPlugin to BrightDigit organization
-- Replace Ink with swift-markdown (SPM dependency)
-- Replace ShellOut with swift-subprocess (SPM dependency)
-- **Deliverable:** Monorepo v1.0.0 with all 17 subrepos
-
-### Phase 2: OpenAPI Generator Migration (4-6 weeks)
-- Migrate SwiftTube from SwagGen to swift-openapi-generator
-- Migrate Spinetail from SwagGen to swift-openapi-generator
-- Replace Prch framework with swift-openapi-runtime
-- Modernize all API client code to async/await
-- **Deliverable:** SwiftTube 1.0.0, Spinetail 1.0.0 (with Apple's OpenAPI generator)
-
-### Phase 3: Swift 6 + Component Migration + Mermaid Support (5-7 weeks)
-- Upgrade all 17 subrepos to Swift 6
-- Enforce component-based HTML generation (deprecate direct Plot API)
-- Create SwiftUI-like component library for site
-- Fix concurrency violations (Testimonial.swift data race)
-- Add Sendable conformances
-- Integrate mermaid.js for diagram rendering
-- Expand test coverage from ~5% to >50%
-- **Deliverable:** Full Swift 6 compliance with component-only architecture and mermaid support
-
-### Phase 4: Publishing Infrastructure (3-4 weeks)
-- Build Buttondown newsletter client (ButtondownKit) using swift-openapi-generator
-- Build Buffer social media client (BufferKit) — handwritten GraphQL, ClientTransport
-- Build MailgunKit sender-only transport for future composability
-- Create PublishKit orchestrator with `SubscriberListProvider` + `NewsletterSender` protocols
-- All modules Swift 6 compliant, Linux-compatible, credentials via env vars only
-- **Deliverable:** Open source publishing pipeline integrated into BrightDigit.com SSG
-
-**Total Duration:** 15-21 weeks (technical phases) + ongoing content optimization
-
-### AI-CITE Content Optimization (parallel, ongoing)
-- Apply AI-CITE framework (Answer-first, Intent-matched, Clear, Indexed, Trusted, Exclusive) to top 10 priority articles
-- Add FAQPage and HowTo JSON-LD structured data to optimized content
-- Create branded BrightDigit methodology frameworks for Exclusive POV
-- Target: 60% AI citation rate within 1 week of optimization per article
-- Reference docs: `.claude/ai-cite-optimization/` — audit, sprint plan, schema design, validation
-- **Deliverable:** All 10 priority articles optimized; JSON-LD schema in `PiHTMLFactory` (Phase 3 integration)
-
-**Key Architectural Changes:**
-1. **Monorepo Consolidation** - 17 packages managed as git-subrepos (Publish ecosystem + BrightDigit + forked plugins)
-2. **Apple Framework Migration** - Ink → swift-markdown, ShellOut → swift-subprocess (ONLY these two dependencies)
-3. **Retained Dependencies** - Kanna, MarkdownGenerator, Yams, Files (Linux compatibility + no alternatives)
-4. **API Client Modernization** - SwagGen/Prch → Apple's swift-openapi-generator
-5. **HTML Generation** - Direct Plot calls → SwiftUI-like components
-6. **Concurrency** - Callbacks/semaphores → async/await/TaskGroup
-7. **Language** - Swift 5.8 → Swift 6 with strict concurrency across all 17 subrepos
-8. **Documentation** - Added mermaid.js support for diagrams in markdown
-9. **Publishing Infrastructure** - ButtondownKit + BufferKit + MailgunKit + PublishKit; open source, no audience data in repo, Linux-compatible
-
-**Success Criteria:**
-- All 17 packages managed as git-subrepos in organized structure
-- swift-markdown and swift-subprocess integrated successfully (ONLY 2 Apple framework replacements)
-- Kanna, MarkdownGenerator, Yams, Files retained (Linux compatibility + no alternatives)
-- Zero concurrency warnings across all 17 subrepos
-- Site output byte-for-byte identical to current production (excluding mermaid diagrams)
-- All 113 newsletters and podcast episodes render correctly
-- Mermaid diagrams render correctly via client-side mermaid.js
-- CI/CD pipeline passes on macOS and Ubuntu (cross-platform compatibility validated)
-- Component-only HTML generation throughout codebase
-- All subrepo updates pushed to upstream repositories
-- Publishing tool compiles with Swift 6 strict concurrency, runs on Linux, and integrates with BrightDigit.com pipeline
diff --git a/.vscode/launch.json b/.vscode/launch.json
index 1784ff83..0c75b6e1 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -6,8 +6,9 @@
"args": [],
"cwd": "${workspaceFolder:brightdigit.com}",
"name": "Debug brightdigitwg",
- "program": "${workspaceFolder:brightdigit.com}/.build/debug/brightdigitwg",
- "preLaunchTask": "swift: Build Debug brightdigitwg"
+ "preLaunchTask": "swift: Build Debug brightdigitwg",
+ "target": "brightdigitwg",
+ "configuration": "debug"
},
{
"type": "swift",
@@ -15,8 +16,9 @@
"args": [],
"cwd": "${workspaceFolder:brightdigit.com}",
"name": "Release brightdigitwg",
- "program": "${workspaceFolder:brightdigit.com}/.build/release/brightdigitwg",
- "preLaunchTask": "swift: Build Release brightdigitwg"
+ "preLaunchTask": "swift: Build Release brightdigitwg",
+ "target": "brightdigitwg",
+ "configuration": "release"
}
]
}
\ No newline at end of file
diff --git a/PRD.md b/PRD.md
new file mode 100644
index 00000000..c96ecc03
--- /dev/null
+++ b/PRD.md
@@ -0,0 +1,366 @@
+# BrightDigit.com — Product Requirements Document
+
+**Repository:** brightdigit/brightdigit.com
+**Last Updated:** 2026-04-13
+**Status:** Living document — reflects current open issues
+
+---
+
+## Overview
+
+This document organizes all open GitHub issues into sequential phases and milestones. The work spans four major concerns:
+
+1. **Content & SEO** — AI-CITE schema optimization and article edits
+2. **Infrastructure Modernization** — Swift 6.3, OpenAPI migration, dependency replacements
+3. **Publishing Pipeline** — Buttondown + Buffer integration, newsletter/podcast tooling
+4. **Platform Migration** — GitHub Pages, AT Protocol support
+
+### Dependency Chain
+
+```
+Phase 0 (housekeeping) ─────────────── independent, can run at any time
+Phase 1 (Monorepo cleanup) ──────────── prerequisite: #36 ✓ (complete)
+Phase 2 (Swift 6.3 main package) ────── requires Phase 1
+Phase 3 (AI-CITE schema + validation) ─ requires Phase 2 (intentional: implement after Swift 6.3 upgrade)
+Phase 4 (OpenAPI migration) ─────────── requires Phase 2 — Swift 6.3-only toolchain
+Phase 5 (Swift 6.3 subrepos + components) requires Phase 4
+Phase 6 (Publishing infra) ──────────── requires Phase 4 (swift-openapi-generator toolchain)
+Phase 7 (Platform migration) ────────── requires Phase 5/6
+Phase 8 (Final cleanup) ─────────────── anytime, low priority
+```
+
+---
+
+## Priority Labels
+
+| Label | Meaning |
+|-------|---------|
+| P0-critical | Must complete first; blocks other work |
+| P1-high | High priority within its phase |
+| P2-medium | Important but not blocking |
+| (none) | Standard priority |
+
+---
+
+## Phase 0: Quick Wins & Housekeeping
+
+**Goal:** Remove stale tooling and fix broken content — no code architecture changes.
+
+| # | Title | Status |
+|---|-------|--------|
+| #11 | Fix Content Updates | Open |
+| #35 | Remove dev-server.sh | Open |
+
+**Notes:**
+- These are independent of all other phases and can be done at any time.
+- #35 removes the shell-based dev server (`dev-server.sh` hardcodes `/Users/leo/.nvm/...`); replaced by the Swift-native approach.
+
+---
+
+## Phase 1: Monorepo Cleanup
+
+**Goal:** Finish loose ends from the monorepo consolidation (#36, completed via #42 and #48).
+
+| # | Title | Status |
+|---|-------|--------|
+| ~~#36~~ | ~~Phase 1: Monorepo Consolidation (17 packages)~~ | **Completed** (#42, #48) |
+| #43 | Upgrade SyndiKit subrepo from 0.3.7 to 0.8.1 | Open |
+| #47 | Remove MarkdownGenerator dependency | Open — fold into Phase 4 #40 |
+
+**Notes:**
+- #43 should be resolved before Phase 2 — SyndiKit 0.3.7 predates the Swift 6.0 concurrency work. 0.8.1 has `Package@swift-6.0.swift` which SPM picks up automatically under Swift 6.3, providing proper `Sendable` conformances. Not a hard blocker (a Swift 6.3 parent can depend on a 5.5 package) but resolving it first avoids concurrency warnings during Phase 2.
+- #47 no longer needs a "bring local" vendor step. `eneko/MarkdownGenerator` is used by exactly one file (`Sources/Tagscriber/KannaMarkdownGenerator.swift`) and swift-markdown (already adopted in Phase 4 #40) covers generation as well as parsing — see the Phase 4 dependency table. The removal will happen as part of the same Phase 4 rewrite that renames `KannaMarkdownGenerator` → `SwiftSoupMarkdownGenerator`.
+
+---
+
+## Phase 2: Swift 6.3 — Main Package
+
+**Goal:** Upgrade the top-level `brightdigit.com` package to Swift 6.3 language mode. Subrepos remain at their current language modes — a Swift 6.3 package can depend on older Swift packages. This unblocks Phase 4 (swift-openapi-generator and swift-subprocess require Swift 6.3+).
+
+**Estimated effort:** 2–3 weeks
+**Dependency:** Phase 1 (#43 resolved).
+
+| # | Title | Status |
+|---|-------|--------|
+| #38 | Swift 6 Language Mode + Component Migration + Mermaid Support | Open |
+| TBD | Fast-deploy: cache prebuilt binary so content-only commits skip `swift build` | Open |
+
+**Content/code separation note:** `Content/` markdown files are already runtime data — they are not compiled into the binary. The problem is CI/CD latency: every commit triggers `swift build` even when only markdown changed. Solution: store the prebuilt `brightdigitwg` binary as a GitLab CI artifact; content-only commits (no `*.swift` or `Package.swift` changes) download the cached binary and run deploy directly. Cache must be invalidated when `Package.resolved` changes.
+
+**Key tasks:**
+- Update `Package.swift`: `// swift-tools-version: 6.3`, `.macOS(.v13)`
+- **Fix `Testimonial.swift` data race (critical):** remove `static var lastID`, make `id` a required parameter
+- Add `Sendable` conformances: `Newsletter.Source`, `YouTubeContent.Source`, `RSSContent.Source`, `BrightDigitPodcast.Source`
+- Fix force-try: `YAMLStringFix.swift:6`, `String.swift:4`, `RSSContent.swift:21`
+
+**Deliverables:**
+- [ ] `brightdigit.com` Package.swift on `swift-tools-version: 6.3`
+- [ ] Zero concurrency warnings in `Sources/`
+- [ ] All tests passing under Swift 6.3
+- [ ] Subrepos unchanged (still at prior language modes)
+
+---
+
+## Phase 3: AI-CITE Optimization
+
+**Milestone:** AI-CITE Phase 1 (target: Feb 28, 2026)
+**Branch:** `ai-cite-optimization` (PR #39)
+**Goal:** Implement structured schema markup and optimize priority articles so BrightDigit content is cited by AI systems (ChatGPT, Google AI Overview, etc.). AI-CITE is fundamentally an integration into the Swift site-building code (`PublishType` protocol + `BrightDigitSite` implementation) — not just article-level content edits. Intentionally sequenced after Phase 2 to avoid doing this work twice across a Swift 6.3 boundary.
+
+**Framework:** AI-CITE — Answer-first, Intent-matched headings, Clear structure, Indexed schema, Trusted sources, Exclusive POV.
+**Target:** 60% of priority articles get AI mentions within 1 week of optimization.
+
+### 3A: Schema Implementation
+
+| # | Title | Priority | Status |
+|---|-------|----------|--------|
+| #56 | Evaluate correct schema.org types for each content section | P0-critical | Open |
+| #18 | Add seomachine.io integration | P1-high | Open |
+| #19 | Implement FAQ Schema Markup in `PiHTMLFactory` | P0-critical | In Progress |
+| #20 | Implement HowTo Schema Markup in `PiHTMLFactory` | P1-high | Open |
+
+**Note:** #56 must be resolved before #19 and #20 — schema type selection drives the implementation.
+
+**Implementation files:**
+- `Sources/PublishType/PageContent.swift` — add `schemaMarkup: String?` requirement (`PublishType` owns the protocol contract)
+- `Sources/BrightDigitSite/Nodes/PiHTMLFactory.HTML.swift` — `head(forPage:)` emits `