ReframeICloudKit.git · AGENTS.md

revision 348ba1d6cac044d75873006d7a5eeacc48220b4f · complete file
# ReframeICloudKit — Agent Guide

Scope: the FCIS Kit boundary between a Fountain-Coach application, macOS Photos, and the iCloud Photos web
session. This package is a library, not a Reframe UI and not an Apple-account client.

Invariants

- `PhotoKitBackend` is the authoritative native route for reading galleries and creating assets in the Photos
  library. It uses only public PhotoKit APIs.
- `ICloudWebBackend` is the supported WebKit session route for a cloud library that macOS does not expose through
  the local Photos library. It never stores Apple credentials, calls private endpoints, or claims an upload without
  visible completion evidence supplied by the host.
- The package never opens a `.photoslibrary` package, reads `Photos.sqlite`, or guesses an external library path.
- The package never puts image bytes, Apple credentials, cookies, or WebKit page state into a Fountain document.
- Placement is represented by typed results. `staged` is not `placed`; `placed` requires a backend receipt.
- AppKit and SwiftUI hosts embed the supplied projection into their existing views. The kit does not present a sheet,
  browser window, or website-like overlay.
- All host-facing state is accessible through stable labels and values. A host remains responsible for its AX surface.
- Multi-step or high-risk changes require an entry in `PLANS.md` before edits.

The package is intentionally independent of Reframe, FountainStore, SecretStore, OpenAI, and any server. Reframe
adapters may persist the returned receipt and lineage in their own governed store.