feed-flow

# AGENTS.md

## Project Overview

FeedFlow is a multi-platform RSS reader built with Kotlin Multiplatform, Compose Multiplatform and SwiftUI.
It targets Android, iOS, macOS, Windows, and Linux.
The app uses SwiftUI for iOS-specific UI components and Compose for all other platforms.
All the business logic is shared via Kotlin Multiplatform.

## Project Structure & Module Organization

### Module Structure
- **core/**: Core domain models and utilities shared across all platforms
- **shared/**: Main business logic, repositories, view models, and data layer
- **sharedUI/**: Compose UI components shared across Android and Desktop
- **database/**: SQLDelight database implementation
- **i18n/**: Internationalization resources
- **feedSync/**: Feed synchronization modules (Dropbox, FreshRSS, iCloud, etc)
- **androidApp/**: Android-specific app implementation
- **iosApp/**: iOS app with SwiftUI
- **desktopApp/**: Desktop app for Windows, Linux, and macOS
- **website/**: Hugo-based website

## Build, Test, and Development Commands

### Build Commands
All Gradle commands in this section should be run with `--quiet --console=plain`.

- `./gradlew --quiet --console=plain detekt allTests` -> Run all checks including tests and linting for Shared code, Android and Desktop
- `.scripts/ci.sh` -> Run the local equivalent of `.github/workflows/code-checks.yaml` (translation refresh, SwiftLint, Gradle checks, Android/Desktop/iOS builds)
- `./gradlew --quiet --console=plain detekt` -> Run static analysis with Detekt for Shared code, Android and Desktop
- `.scripts/ios-format.sh` -> Format iOS code through swiftformat and swiftlint
- `./gradlew --quiet --console=plain test` -> Run all tests for Shared code, Android and Desktop
- `.scripts/refresh-translations.sh` -> Regenerate i18n translation code after adding new translations
- `./gradlew --quiet --console=plain :androidApp:assembleGooglePlayDebug` -> Build the Android debug APK (then deploy/run with the `android` CLI, see "Running & validating the Android app")
- `./gradlew --quiet --console=plain :androidApp:compileGooglePlayDebugKotlin` -> Quick compile check for Android (no APK assembly)
- `.scripts/run-android.sh` -> Install and launch Android Google Play debug (wraps `:androidApp:installGooglePlayDebug`)
- `.scripts/add-android-feed.sh <url>...` -> Add RSS feeds to the app on a connected device via the share intent, without typing URLs on the device
- `./gradlew --quiet --console=plain desktopApp:run` -> Run Desktop app
- `./gradlew --quiet --console=plain :desktopApp:compileKotlinJvm` -> Quick compile check for Desktop
- `./gradlew --quiet --console=plain :desktopApp:jvmMainClasses` -> Compile Desktop main classes (faster than full build)
- `.scripts/delete-desktop-debug-db.sh` -> Delete local Desktop debug database and prefs
- `./gradlew --quiet --console=plain :shared:compileKotlinJvm` -> Quick compile check for shared module only (fastest iteration)
- `./gradlew --quiet --console=plain :feedSync:feedbin:build` -> Build a specific feedSync sub-module (pattern: `:feedSync:<module>:build`)
- `./gradlew --quiet --console=plain :desktopApp:packageDistributionForCurrentOS` -> Package desktop app distribution for the current OS

### Android baseline profiles

The committed profiles in `androidApp/src/main/generated/baselineProfiles/` (`baseline-prof.txt`, `startup-prof.txt`) are generated by the `:benchmarks` module and shared by both flavors (`mergeIntoMain = true`). Do not hand-edit them.

- `./gradlew --quiet --console=plain :androidApp:generateBaselineProfile` -> Regenerate the profiles; needs a connected device or emulator on API 33+ (or rooted). Commit the updated files.
- `./gradlew --quiet --console=plain :benchmarks:connectedGooglePlayBenchmarkReleaseAndroidTest` -> Run the `StartupBenchmark` macrobenchmark (compares startup with/without the profile; run on a physical device for meaningful numbers)
- Regenerate before releases or when startup/feed-list code paths change significantly; a slightly stale profile is still effective.
- The `nonMinifiedRelease`/`benchmarkRelease` build types created by the baseline profile plugin need a `google-services.json` in `androidApp/src/nonMinifiedRelease/` and `androidApp/src/benchmarkRelease/` (see Initial Setup).
- The E2E seed deep links are debug-only, so the generator journey is cold start plus a guarded feed-list scroll on the release-like build.

### Running & validating the Android app

Use the [Android CLI](https://developer.android.com/tools/agents/android-cli) (`android`, installed globally; SDK at `~/Library/Android/sdk`) as the default tool to deploy, run, and validate Android.

**Auto-update on session start.** The first time `android` is invoked in a session, check its output for a notice like `A new version of Android CLI is available (<version>). Please run 'android update' to install it.` If you see it, run `android update` immediately, then tell the user which version was installed and continue with the original task. Don't ask for permission — this is a routine self-update.

**Precondition — Android CLI must be installed.** Before running any of the commands below, verify it is available with `command -v android`. If it is not installed, stop and ask the user to install it:

> The `android` CLI is required to deploy and validate the app. Install it by following the official guide: https://developer.android.com/tools/agents/android-cli
> After installation, install the companion skill so agents (Claude Code, codex) know how to drive it:
> ```
> android init
> ```
> Restart your shell and confirm with `android --version`, then re-run the task.

**Precondition — a device/emulator must be running.** Check with `adb devices`. Do not assume an emulator: use the first device returned by `adb devices` (real device or emulator — both are fine). If none is connected, default to the resizable emulator: `android emulator start Resizable_Experimental` (verify the exact AVD name with `android emulator list` if it fails).

**Resizable emulator display mode.** When testing with the resizable emulator and the task needs a specific form factor, set it before building/running:

```bash
adb emu resize-display 0 # phone
adb emu resize-display 1 # foldable
adb emu resize-display 2 # tablet
```

Validate a UI change end to end:
1. Build + deploy: `./gradlew --quiet --console=plain :androidApp:assembleGooglePlayDebug`, then `android run --apks=androidApp/build/outputs/apk/googlePlay/debug/androidApp-googlePlay-debug.apk` (`--device=<serial>` to pick a device; `.scripts/run-android.sh` covers the routine install+launch loop).
2. Inspect structure/text/state with `android layout --pretty`. To confirm a specific change, capture the layout before and after the change, then use `android layout --diff` to see only what moved.
3. For purely visual changes the layout tree can't show (color, spacing, fonts), use `android screen capture --output=ui.png --annotate`. Use `android screen resolve --screenshot=ui.png --string="input tap #<n>"` to turn a labeled element into tap coordinates when you need to drive the UI to the screen under test.

For Android API/library questions, `android docs search '<query>'` before falling back to web search.

For anything deeper — SDK package management (`android sdk ...`), device interaction, or journey/UI tests — consult the globally-installed `android-cli` skill instead of expanding this section.

### Running & validating the Desktop app

When you need to run the Desktop app for testing, UI iteration, or user-visible validation, prefer the Compose Hot Reload MCP server configured in `.mcp.json`:

```bash
./gradlew --quiet --console=plain :desktopApp:hotMcpServerJvm
```

Use the Gradle daemon for manual local runs so repeated desktop iterations stay fast. The checked-in `.mcp.json` may still pass `--no-daemon` because JetBrains' AI-agent example does that for MCP client-managed server processes.

Use the MCP tools when you need to interact with the running Desktop app: check status, reload code changes, list windows, capture screenshots, inspect the semantic tree, click/type/scroll, or resize windows. The MCP server is experimental in Compose Hot Reload; if it is unavailable or not connected, fall back to `./gradlew --quiet --console=plain desktopApp:run` and note the limitation in handoff.

### Local Klead development

Klead resolves from Maven Central by default. Its composite-build substitution in `settings.gradle.kts` is deliberately commented out; only enable it for explicit local Klead work, using `-Pfeedflow.kleadPath=<checkout>` (default: `../../klead`), and do not commit that local substitution.

### Maestro E2E tests

When writing or running Maestro E2E tests, follow `e2e/maestro/maestro-e2e-guide.md`.
The full catalog of existing flows lives in `e2e/maestro/maestro-e2e-tests.md`; do not mark a test done until the required Maestro flow passes.
When changing a user-visible feature, add or update Maestro coverage if the behavior can be exercised with existing app UI, debug seed deep links, fixtures, or test tooling without adding production-only code paths. If Maestro coverage is not feasible, document the limitation in `e2e/maestro/maestro-e2e-tests.md`.

Quick local smoke checks:
- `e2e/scripts/run-android-smoke.sh`
- `e2e/scripts/run-ios-smoke.sh`

Full automated E2E checks before release:
- `e2e/scripts/run-android.sh`
- `e2e/scripts/run-ios.sh`

When the user asks for the full Maestro release gate or a failure summary, use the repo-local `run-maestro-release-tests` skill. Its runner builds/installs both platforms, runs smoke + regression flows, continues after failures, and writes `report.html`, `report.md`, and logs under `.tmp/maestro-release-tests/<timestamp>/`.
Each Maestro flow has a three-minute limit and the runner retries only driver/transport failures (up to three attempts). Treat a timeout or device-server failure as infrastructure first; inspect the archived per-attempt logs before changing app code.

After any local Maestro run, restore the development subscriptions before handoff with `feedflow-restore-dev-feeds --platform android` or `--platform ios`. The all-platform wrapper and release runner do this automatically when the command is installed; run it explicitly after a single flow or a failed run.

Use the debug seeding deep links documented in that guide. Do not depend on live feeds, OAuth, or previous app state in smoke or regression flows.

### iOS Project Generation

The iOS Xcode project (`iosApp/FeedFlow.xcodeproj`) is generated from `iosApp/project.yml` by [XcodeGen](https://github.com/yonaskolb/XcodeGen) and is NOT committed to git. Regenerate it with:

```bash
cd iosApp && ./.scripts/generate-project.sh
```

This requires XcodeGen installed (`brew install xcodegen`, or `mint bootstrap` using `iosApp/Mintfile` which pins the version). Regenerate whenever `project.yml`, iOS source folder structure, xcconfigs, entitlements, or SPM dependencies change. The wrapper script also creates `Assets/Config-Debug.xcconfig` from the tracked template when it is missing, post-fixes `lastKnownFileType` for iOS 26 `.icon` bundles, and injects `wasCreatedForAppExtension="YES"` into the Widget/Share extension schemes (XcodeGen drops this when the scheme also launches the host app — yonaskolb/XcodeGen#1523). SPM pins are managed via `exactVersion:` entries in `project.yml`; no `Package.resolved` is tracked.

### Building for iOS Simulator

- If using XcodeBuildMCP, use the installed XcodeBuildMCP skill before calling XcodeBuildMCP tools.
- The xcodeproj must exist locally. Run `cd iosApp && ./.scripts/generate-project.sh` first if it's missing.
- XcodeBuildMCP has repo-local defaults in `.xcodebuildmcp/config.yaml`; prefer the current CLI shape:

```bash
xcodebuildmcp simulator build
```

To build and launch in one step:
```bash
xcodebuildmcp simulator build-and-run
```

If the MCP server is registered in the current agent session, use the equivalent `simulator/build` or `simulator/build-and-run` tool; do not use the old `build_sim_name_proj` tool name.
Do not set `derivedDataPath` in `.xcodebuildmcp/config.yaml` by default. Leaving it unset lets XcodeBuildMCP use its external per-workspace DerivedData path, which avoids branch-local artifacts and avoids sharing mutable Xcode build products across concurrent worktrees. Set it only for a temporary cache investigation or an explicit reproducibility test.


### Running Specific Tests
- `./gradlew --quiet --console=plain :shared:allTests` -> Run all shared module tests across supported targets
- `./gradlew --quiet --console=plain :shared:jvmTest --tests "com.prof18.feedflow.shared.presentation.SomeTest"` -> Run a specific test class on JVM
- `./gradlew --quiet --console=plain :shared:iosSimulatorArm64Test` -> Run shared tests on iOS simulator

### Build Verification Process

IMPORTANT: When editing code, you MUST:
1. Build the project after making changes
2. Fix any compilation errors before proceeding
   Be sure to build ONLY for the platform you are working on to save time.

## Handing off

Before handing off you must:
1. Run `.scripts/refresh-translations.sh` before the Gradle checks if you changed translation resources
2. Run `./gradlew --quiet --console=plain detekt allTests` to ensure Kotlin/shared/Android/Desktop checks pass - don't run it if you modified only swift files
3. Run `.scripts/ios-format.sh` to format iOS code - only run if you made changes on the iOS app
4. If you changed iOS code, run `xcodebuild -project iosApp/FeedFlow.xcodeproj -scheme FeedFlow -destination 'platform=iOS Simulator,name=iPhone 17 Pro' build -quiet` before handoff; rerun without `-quiet` only if you need the full diagnostics
5. Fix any issues found during the above steps

### Initial Setup (for building from scratch)
```bash
# Android: Copy dummy google-services.json
cp config/dummy-google-services.json androidApp/src/debug/google-services.json
cp config/dummy-google-services.json androidApp/src/release/google-services.json

# Android: baseline profile build types also need it (profile generation/benchmarks)
mkdir -p androidApp/src/nonMinifiedRelease androidApp/src/benchmarkRelease
cp config/dummy-google-services.json androidApp/src/nonMinifiedRelease/google-services.json
cp config/dummy-google-services.json androidApp/src/benchmarkRelease/google-services.json

# iOS: Copy dummy GoogleService-Info.plist
cp config/dummy-google-service.plist iosApp/GoogleService-Info-dev.plist
cp config/dummy-google-service.plist iosApp/GoogleService-Info.plist

# iOS: Create Config.xcconfig
cp iosApp/Assets/Config.xcconfig.template iosApp/Assets/Config.xcconfig
```

For compile-only local/CI iOS builds without real sync credentials, you can use `cp config/dummy-config.xcconfig iosApp/Assets/Config.xcconfig` instead.

For Google Play listing/bootstrap checks, prefer `FEEDFLOW_PLAY_CONFIG_JSON=/path/to/play_config.json ./gradlew --quiet --console=plain :androidApp:bootstrapGooglePlayReleaseListing`. Do not assume an uncommitted repo-root `play_config.json` exists in automation worktrees.

## Testing

Project documentation lives in **`docs/`**; start with [the documentation index](docs/README.md). Keep agent skills in `.ai/skills/`.

When writing tests, follow the comprehensive testing guide at **`docs/TESTING.md`**.

Key points:
- All tests extend `KoinTestBase` for dependency injection
- Use Turbine for Flow testing
- Prefer fakes over mocking libraries
- Use data generators from `shared/src/commonTest/.../test/generators/`
- For sync service tests, use the `feedSync/test-utils` module (provides mock HTTP engines and Koin modules for GReader/Feedbin)
- Run specific test classes with `--tests "fully.qualified.ClassName"` to iterate quickly

For Sentry crash notes, Sentry issue URLs, or event IDs, use the repo-local `sentry-note-crash-fix` skill. Confirm the live Sentry event when possible, identify the first relevant first-party frame, inspect dependency versions and affected platform code, then validate the narrow fix with the affected platform build before the full gate.

For Miniflux/GReader sync failures, compare FeedFlow's exact requests and headers against the upstream service behavior before changing protocol logic. Miniflux bad sync tokens are detected from the `X-Reader-Google-Bad-Token` header and mapped to `FeedSyncError.GReaderBadToken` (`FS11`); cover changes with `feedSync/test-utils` mocks.

## General rules:

- For cloud-backup sync, follow `docs/CLOUD_SYNC_TESTING.md`; the deterministic harness runs through `allTests`. For live provider checks or adding a provider, use `.ai/skills/validate-cloud-sync/SKILL.md` and `docs/CLOUD_SYNC_LIVE_TESTING.md`. The optional physical-iPhone controller in `tools/cloud-sync-live/` does not replace that Gradle gate.

- DO NOT write comments for every function or class. Only write comments when the code is not self-explanatory.
- If you touch or create any business logic, ensure it's thoroughly tested with unit tests.
- DO NOT excessively use try/catch blocks for every function. Use them only for the top caller or the bottom callers, depending on the cases.
- ALWAYS run gradle tasks with the following flag: `--quiet --console=plain`
- Prefer keeping data classes and other simple model types at the bottom of a file, or in a dedicated model file when they are shared by multiple classes.
- Android app modules use AGP 9's built-in Kotlin support; do not re-add `org.jetbrains.kotlin.android`. Android and Desktop app version values come from the `com.feedflow.versioning` convention plugin, not `versioning.gradle.kts`.
- Detekt is still on the `1.23.x` line, so keep `io.nlopez.compose.rules:detekt` on `0.4.x` unless the repo migrates to Detekt 2; `0.5.0+` is Detekt 2-only for this repo.
- Detekt's `MagicNumber` rule has `ignoreNamedArgument: true`. Do NOT extract a literal into a private constant when it is passed as a named argument (e.g. `Modifier.widthIn(max = 180.dp)`, `shadowElevation = 3.dp`, `.copy(alpha = 0.8f)`) — inline it. Only extract a named constant when the literal is a positional argument that Detekt would flag (e.g. `.zIndex(0.5f)`, `.height(28.dp)`); values in `ignoreNumbers` (`-1, 0, 1, 2`) never need one.
- Every `DropdownMenu` (Android, shared, and Desktop) must pass `shape = MaterialTheme.shapes.large` so menus stay coherent with the rounded toolbars. There is no shared wrapper — set it explicitly on each new `DropdownMenu`.

### Desktop screens/windows
- For desktop settings/details pages opened from the main screen, prefer a dedicated `DialogWindow` instead of in-window navigation.
- Reuse `desktopApp/src/jvmMain/kotlin/com/prof18/feedflow/desktop/ui/components/DesktopDialogWindow.kt` for new desktop windows instead of duplicating window setup.
- Use `desktopApp/src/jvmMain/kotlin/com/prof18/feedflow/desktop/main/DesktopDialogWindowNavigator.kt` to open/close windows from `MainWindow` (add destinations to the enum and keep visibility state there).
- Keep the screen body content as a composable content block and avoid duplicating content calls; apply platform conditionals only to wrapper chrome (for example, toolbar/title handling).
- On macOS, keep transparent title bar handling inside the reusable desktop window wrapper; on other desktop platforms avoid adding duplicate custom title UI.

### Desktop OS integration
- Use `openUriSafely` for desktop link opening so unsupported or malformed URLs can fall back to copying instead of crashing the app.

### Git Commit Messages
When creating commits:
- Use simple, one-liner commit messages
- DO NOT include phase numbers (e.g., "Phase 1", "Phase 2")
- DO NOT add "Generated with Claude Code" attribution
- DO NOT add "Co-Authored-By: Claude" attribution
- Example: `git commit -m "Add foundation for unified article parsing system"`

### macOS Desktop Code Signing
- Native libraries in `desktopApp/resources-sandbox/macos-arm64/` must be signed with the Mac App Store certificate when it is renewed.
- Sign with: `codesign --force --timestamp --options runtime --sign "3rd Party Mac Developer Application: Marco Gomiero (Q7CUB3RNAK)" <path>`
- Verify with: `codesign -dvvv <path>`

### iOS Development
- ALWAYS build with xcodebuild with -quiet flag when building for iOS. If the command returns errors you may run xcodebuild again without the -quiet flag.
- Direct xcodebuild alternative: `xcodebuild -project iosApp/FeedFlow.xcodeproj -scheme FeedFlow -destination 'platform=iOS Simulator,name=iPhone 17 Pro' build -quiet`
- IMPORTANT: The project now supports iOS 26 SDK (June 2025) while maintaining iOS 18 as the minimum deployment target. Use #available checks when adopting iOS 26+ APIs.
- Keep app-group database work that may outlive an iOS foreground interval inside `withSuspensionGuard`; it uses `NSProcessInfo` and also works in the widget and share extensions.
- Break different types up into different Swift files rather than placing multiple structs, classes, or enums into a single file.
- Keep accessibility identifier enums in separate `*AccessibilityIdentifiers.swift` files, not appended to view files.
- Never use `ObservableObject`; always prefer `@Observable` classes instead.
- Never use `Task.sleep(nanoseconds:)`; always use `Task.sleep(for:)` instead.
- Avoid `AnyView` unless it is absolutely required.
- Avoid force unwraps and force `try` unless it is unrecoverable.
- For SwiftUI screens that use `BrowserSelector`, pass the same environment instance into nested `NavigationLink` destinations and sheets so link-opening and reader-mode settings do not reset while navigating.
- In the SwiftUI feed list, keep row callbacks narrowly captured and put `.refreshable` at the screen boundary; broad environment captures or nested refresh wrappers can invalidate every visible row while scrolling. Validate changes with a warmed-up Instruments capture on a physical iPad as described in `e2e/maestro/maestro-e2e-tests.md`.

### Reader mode
- Klead is the sole reader-content engine on Android, Desktop, and iOS; keep parsing in the shared pipeline rather than adding a platform HTML parser. Shared HTML parsing uses `KsoupHtmlParser`.
- Use `ReaderModeEligibility.canOpenReaderMode` / `FeedItemUrlInfo.canOpenWebReaderMode()` as the shared gate before opening reader mode on Android, Desktop, and iOS. Ineligible links such as blank, non-http(s), media/PDF/download URLs, YouTube, and Telegram should fall back to the configured browser or `ContentNotAvailable` behavior instead of attempting reader parsing.
- URL-less items are a separate case: they are never web-reader eligible, but they still open in the reader from their feed content. Check `FeedItemUrlInfo.hasNoUrl()` first (it must bypass the whole `linkOpeningPreference` branch, since there is no URL any browser could open).

### HTTP clients
- Every Ktor client that can reach the Darwin engine must install `rejectUnsafeHosts()` after its plugins are configured. Its `HttpSend` interceptor validates every request and redirect hop, preventing malformed percent escapes or bare colons in hosts from terminating iOS.

### Timeline pagination
- The feed list pages with a keyset cursor on `(pub_date, url_hash)`, never `LIMIT`/`OFFSET`: the timeline filters on `is_read` while mark-as-read-on-scroll mutates it mid-scroll, so a positional offset skips articles (issue #1319). Read **`docs/PAGINATION.md`** before changing `selectFeeds` in `FeedItem.sq` or the cursor handling in `FeedStateRepository`.
- The cursor predicate must mirror the query's `ORDER BY` exactly, including SQLite NULL placement for nullable `pub_date`; invalidate the cursor only after a query succeeds.

### Internationalization
- String resources are located in `i18n/src/commonMain/resources/locale/values-[language]/`
- Run .scripts/refresh-translations.sh after adding a new translation, to re-generate the kotlin code
- Store screenshots for **all** platforms (Android phone/tablet, iPhone, iPad, macOS, Windows) are rendered from repo code by `tools/screenshots/` (`node render.mjs --all`, then `node verify.mjs`), not Figma. Use the repo-local `render-store-screenshots` skill when translations change; it enforces the spacing/padding floors.
- Use the repo-local `translation-release-audit` skill for weekly or release checks of app translations, store copy, generated Play listing files, live store metadata, and screenshot copy/assets. Do not upload store metadata/screenshots unless the user explicitly asks.
- NEVER add hardcoded strings in the code. Always use the i18n resources.
- NEVER try to translate other languages by yourself. Add only the English strings. The translations will be handled by professionals later.

### Flatpak / Linux Desktop
- `.scripts/flatpak-build-setup.sh` -> Prepare the project for Flatpak builds (sets release props, disables JetBrains JDK vendor, disables toolchain auto-provisioning, comments out Android-only Gradle plugins)
- `.scripts/disable-android-for-flatpak.sh` -> Comments out all Android-related Gradle config across all `build.gradle.kts` and build-logic files; excludes `androidApp` from `settings.gradle.kts`
- Flatpak packaging files live in `desktopApp/packaging/flatpak/` (manifest, launch script, desktop entry, AppStream metadata, icon)
- The `flatpak=true` property in `desktopApp/src/jvmMain/resources/props.properties` is used to disable platform-specific features (e.g., Google Drive sync) in Flatpak builds
- HiDPI scaling for the JVM uses `sun.java2d.uiScale` JVM argument. For local testing: `./gradlew --quiet --console=plain desktopApp:run -PjvmArgs="-Dsun.java2d.uiScale=2.0"`

### CI/CD
- CI config: `.github/workflows/code-checks.yaml`
- Pipeline: `checks` (macos-26, detekt + allTests + swiftlint) -> `build-android-app` + `build-desktop-app` + `build-ios-app` (in parallel)
- iOS CI build forces arm64 simulator architecture: `xcodebuild -project iosApp/FeedFlow.xcodeproj -configuration Debug -scheme FeedFlow -sdk iphonesimulator -destination "generic/platform=iOS Simulator" ARCHS=arm64 ONLY_ACTIVE_ARCH=YES build | xcbeautify --renderer github-actions`
- CI runs `.scripts/refresh-translations.sh` before checks; do this locally before pushing if translations changed
- Debugging CI failures: `gh run list --limit=10`, then `gh run view <run-id> --log`
- Red CI recovery loop: `gh run rerun <run-id>` (or `gh run rerun <run-id> --failed`), then fix and push until green

### Microsoft Store (`pcenter`)

The Store is driven by [`pcenter`](https://github.com/prof18/pcenter-cli), which replaced the
PowerShell scripts in `.github/scripts/`. Locally: `brew install prof18/tap/pcenter`. In CI it
runs in `windows-release.yml`'s `publish-store` job — a separate Linux job that takes the MSIX
from the Windows build artifact, so a publish that fails on its own terms is re-runnable in a
minute instead of rebuilding the package for an hour. Bump `PCENTER_VERSION` in its "Install
pcenter" step to move the pinned version.

- Reading changes nothing and is the place to start: `pcenter listing show`,
  `pcenter submission status`, `pcenter rollout status`, `pcenter locales list`.
- Credentials: `~/.config/pcenter/credentials.env` locally (`pcenter auth login`), `MS_STORE_*`
  from repository secrets in CI. Never commit them.
- `assets/storecopy/<locale>/` is the source of truth for listing copy. `.pcenter/` is a
  gitignored scratch snapshot — never commit it, never hand-edit it.
- **Never `pcenter listing push --yes` or `submission commit` unless the user explicitly asks.**
  `--dry-run` first, always.

The MSIX itself is built by `.scripts/package-msix.ps1`, which packs the jpackage app image
(`createReleaseDistributable`) with `makeappx` against `.github/msix-manifest-template.xml`.
Do not reintroduce the MSIX Packaging Tool / MSI-conversion route: it needs the
`Msix.PackagingTool.Driver` FOD, which stopped installing on the hosted Windows image in
August 2026, and the tool's own DISM call times out after 10 minutes with no way to extend it.
Package languages still come from `.github/msix-resources-template.xml`. `Identity/Name` and
`Identity/Publisher` in the manifest must match Partner Center or the upload is rejected.

To test that package locally, `.scripts/install-msix-dev.ps1` unpacks it, rewrites the identity
to `MarcoGomiero.FeedFlowRSSReaderDev` and the display name to "FeedFlow (Dev)", and registers
it. The rename matters: registering under the shipping identity makes Windows treat the build
as an update to an installed Store FeedFlow and replace it. Needs Developer Mode, no signing.
It registers loose files out of `desktopApp/build`, so re-run it after every rebuild; clean up
with `-Uninstall`. Running the app image directly is the quicker check, but only the registered
package exercises the manifest, the Start-menu entry and the tiles.

For the actual workflows — syncing listing text, replacing screenshots, adding or removing a
Store language, Store field limits, rescuing a stuck submission or rollout — use the repo-local
`update-microsoft-store-listing` skill instead of expanding this section.

More agent context in prof18/feed-flow

2 other files this repository gives its agents.