@topy-ai/maggie 0.7.47 → 0.7.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.47",
+  "version": "0.7.48",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/browser-inspection.md

@@ -75,3 +75,28 @@ appearance. For every stateful component capture state A and state B and
 record the trigger and transition. Keep screenshots and extracted data under
 the target's namespaced research root so multiple URLs cannot overwrite one
 another.
+
+## Network interception and write safety
+
+Any skill that drives a browser against a running app (QA, clone, design
+review) must assume the app may talk to a real API. A local development build
+is often configured with the production API base URL, so a click in local QA
+can change live accounts.
+
+- Do not rely on page-level stubs such as overriding `window.fetch` from the
+  console or an injected script. Bundled API clients usually capture `fetch`
+  at module load, use `XMLHttpRequest`, or run in a service worker, so the
+  override never sees their requests.
+- Intercept at the network layer instead: Playwright `page.route()` /
+  `context.route()`, Puppeteer request interception, or CDP `Fetch.enable`.
+  Deny by default every non-GET request to a production origin and let only
+  explicitly listed reads through.
+- Verify the interception before any write flow: trigger one harmless request
+  and confirm in the browser's network log that it was intercepted, not sent.
+- Without network-layer interception, run write flows only against a
+  non-production API, or after the user gives explicit consent naming the
+  account and the data that will change. Record a backup or restore path first.
+
+`maggie qa start --api-base URL --production-api URL` records the API target.
+Scenarios marked `"mutates": true` are blocked against a production API unless
+`--allow-production-writes` is given. See the `maggie-qa-workflow` skill.

package/references/provider-adapter-contract.md

@@ -150,6 +150,39 @@ image-processing contract: optimisation may use Cloudflare Images
 transformations, Astro build tooling or a provider-specific implementation
 behind the same interface.
 
+## OAuth connections
+
+A provider connection is only as reliable as its weakest connect path:
+
+- Each adapter declares one canonical OAuth scope set. Every client that
+  starts the flow (dashboard, mobile app, CLI) requests exactly that set.
+  LinkedIn invalidates a member's earlier tokens when a later sign-in asks for
+  a different scope set, so a mobile app that omits `email` silently revokes
+  the dashboard's token while the database still says `active`.
+- Prefer one OAuth client per product. When a client ID is shared with other
+  products or callbacks, record it as `client_shared_with`; their sign-ins can
+  revoke this product's tokens unless they use the identical scope set.
+- Treat stored connection status as a cache. A token that the provider has
+  revoked, or that the serving host cannot decrypt, is `needs_reconnect`
+  before anything is scheduled on it — not when a post fails.
+- Provider media URLs (for example `media.licdn.com` with an `e=` expiry) are
+  signed and expire. Cache the bytes in owned storage or refresh on readback.
+
+`maggie tool maggie_social_share.py adapters` and `connections` check these
+rules from a redacted JSON manifest; see the Social Share skill for shapes.
+
+## Structured model output
+
+Keep structured-output schemas small. Gemini rejected a JSON schema whose enum
+had 125 values with `400 INVALID_ARGUMENT`, and the caller silently fell back
+for every request. For a large vocabulary (styles, categories, catalogue IDs):
+
+1. ask for a free string (optionally with a short list of examples in the
+   prompt) instead of a large `enum`;
+2. validate the returned value server-side against the authoritative list;
+3. treat a schema rejection or an unknown value as a visible, counted failure —
+   never a silent fallback to a default.
+
 ## Adding a provider
 
 1. Implement the relevant interface in `src/lib/providers/`.