docs: add booru api references and held-post plans

1 files changed, 68 insertions, 0 deletions

diff --git a/docs/plans/2026-02-23-held-posts-toggle-implementation.md b/docs/plans/2026-02-23-held-posts-toggle-implementation.md
new file mode 100644
index 0000000..7f84e55
--- /dev/null
+++ b/docs/plans/2026-02-23-held-posts-toggle-implementation.md
@@ -0,0 +1,68 @@
+# Held Posts Toggle Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a settings toggle to allow showing held posts on Moebooru providers, while keeping default feed behavior aligned with website ordering.
+
+**Architecture:** Persist a global boolean in `SettingsManager`, pass it into `BooruManager`, and conditionally apply default `holds:false` in the Moebooru tag helper. Expose the toggle in Provider settings and rebuild manager instances when the setting changes so requests immediately reflect the new behavior.
+
+**Tech Stack:** Swift, SwiftUI, `@AppStorage`, XCTest source-assertion tests.
+
+---
+
+### Task 1: Add failing tests for toggle persistence and wiring
+
+**Files:**
+- Modify: `SoraTests/ViewDerivedDataTests.swift`
+
+**Step 1: Write failing tests**
+- Add a test asserting `SettingsManager` contains `@AppStorage("showHeldMoebooruPosts") var showHeldMoebooruPosts = false`.
+- Add a test asserting `MainView` passes `showHeldMoebooruPosts: settings.showHeldMoebooruPosts` when creating `BooruManager`.
+- Add a test asserting `BooruManager.moebooruTagString` guards on `showHeldMoebooruPosts` and bypasses forced `holds:false` when enabled.
+
+**Step 2: Run tests to verify failure**
+- Run: `xcodebuild -scheme Sora -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.2' -only-testing:SoraTests/ViewDerivedDataTests test`
+- Expected: New tests fail due missing setting/wiring.
+
+### Task 2: Implement the setting and manager behavior
+
+**Files:**
+- Modify: `Sora/Data/Settings/SettingsManager.swift`
+- Modify: `Sora/Data/Booru/BooruManager.swift`
+- Modify: `Sora/Views/MainView.swift`
+- Modify: `Sora/Views/Settings/Section/SettingsSectionProviderView.swift`
+
+**Step 1: Add setting storage**
+- Add `@AppStorage("showHeldMoebooruPosts") var showHeldMoebooruPosts = false` to `SettingsManager`.
+
+**Step 2: Thread setting into manager**
+- Add `showHeldMoebooruPosts` init param + stored property in `BooruManager`.
+- Update Moebooru tag helper:
+  - Respect explicit `holds:*` as-is.
+  - If `showHeldMoebooruPosts == true`, return raw tags (no forced filter).
+  - Else append `holds:false` default.
+
+**Step 3: Wire manager creation points**
+- Update `MainView` manager constructors to pass `showHeldMoebooruPosts: settings.showHeldMoebooruPosts`.
+- Add `.onChange(of: settings.showHeldMoebooruPosts)` to rebuild manager and refresh feed.
+
+**Step 4: Expose toggle in settings UI**
+- Add `Toggle("Show Held Posts", isOn: $settings.showHeldMoebooruPosts)` to Provider settings section.
+- Add concise help text that this affects Moebooru feeds.
+
+### Task 3: Verify and finalize
+
+**Files:**
+- Modify (if needed): `SoraTests/ViewDerivedDataTests.swift`
+
+**Step 1: Run targeted tests**
+- Run: `xcodebuild -scheme Sora -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.2' -only-testing:SoraTests/ViewDerivedDataTests test`
+- Expected: PASS.
+
+**Step 2: Run lint**
+- Run: `swiftlint lint --quiet`
+- Expected: PASS.
+
+**Step 3: Summarize behavior**
+- Confirm default (`false`) preserves website-aligned ordering.
+- Confirm toggle (`true`) includes held posts for Moebooru providers.