docs: add booru api references and held-post plans

2 files changed, 97 insertions, 0 deletions

diff --git a/docs/plans/2026-02-23-held-posts-toggle-design.md b/docs/plans/2026-02-23-held-posts-toggle-design.md
new file mode 100644
index 0000000..b629f0f
--- /dev/null
+++ b/docs/plans/2026-02-23-held-posts-toggle-design.md
@@ -0,0 +1,29 @@
+# Held Posts Toggle Design
+
+## Goal
+Add a user setting that allows Moebooru providers to include held posts in the feed when desired, while preserving current default ordering behavior.
+
+## Problem
+Konachan and yande.re API results can diverge from website ordering because held posts are included unless explicitly filtered. We currently force `holds:false` by default to match the website feed, but users need an option to view held posts.
+
+## Decision
+Implement a global persisted setting: `showHeldMoebooruPosts` (default `false`).
+
+- When `false`: Moebooru requests continue to append `holds:false` unless user already provides `holds:*`.
+- When `true`: Moebooru requests do not add a default `holds:false` filter; explicit `holds:*` tags still win.
+
+## Scope
+- Data model: Add `@AppStorage` boolean to `SettingsManager`.
+- Networking: Thread the setting into `BooruManager` and its Moebooru tag helper.
+- UI: Add a toggle in Provider settings.
+- Wiring: Rebuild `BooruManager` when setting changes so feed refresh reflects the new mode.
+- Tests: Add source-based checks for setting persistence, manager wiring, and Moebooru filter behavior.
+
+## Non-Goals
+- Per-provider held-post settings.
+- Changing Danbooru/Gelbooru behavior.
+- Advanced moderation controls beyond `holds:*` behavior.
+
+## Rollout Behavior
+- Existing users default to `false`, preserving current website-aligned feed order.
+- Users can opt in to include held posts through settings.
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.