Fusion - the Fusion 360 Bridge

@@ -0,0 +1,93 @@+---+name: fusion-aps-search+description: THE definitive reasoning for the Fusion bridge's APS cloud-file search — WHY we use Autodesk Platform Services (APS) Data Management for fast search, why the slow Fusion add-in search is unacceptable, why the bridge runs its own OAuth, and the hard payment rules. READ THIS FIRST before proposing ANY change to fusion cloud search, before "reconsidering" APS, or before suggesting a fallback. Stops the recurring loop of re-deriving the same conclusions. Trigger words — fusion cloud search, fusion_aps_search, aps search, why aps, fusion search slow, fusion_search_cloud_files, fusion_walk_cloud_tree, search fusion files, cloud file search, fusion data management.+---++# Why the Fusion bridge uses APS for cloud search (settled — do NOT relitigate)++This exists because the reasoning kept getting re-derived (and re-asked of John, who is+sick of answering). It is SETTLED. Read it, follow it, don't reopen it.++## The goal+Adom users need to search their Fusion 360 **cloud files FAST** — by name — for every Adom+user, with AI-driven setup. "Fast" = seconds, not minutes.++## The garbage we do NOT use (and must NOT propose as the answer)+`fusion_search_cloud_files` and `fusion_walk_cloud_tree` exist in the bridge but are+**UNACCEPTABLE for search**: they go through Fusion's free add-in Data API, which is so+rate-limited that walking a real project takes **30+ MINUTES**. They are garbage for this+use case. **NEVER** fall back to them as "the free option" — slowness this bad is a+non-starter. If you catch yourself about to recommend "just use the add-in search since it's+free / no card," STOP — that's the exact wrong conclusion John has corrected multiple times.++## The answer: APS Data Management API (server-side index)+Autodesk Platform Services' **Data Management API** has a **server-side index** → name search+returns in seconds. This is the ONLY way to get fast search. This is why APS exists in the+bridge. Speed is the whole point; APS is how we get it.++## Why the bridge runs its OWN OAuth (can't piggyback Fusion's login)+We WANTED to reuse Fusion's existing in-session token (no setup, no second login). It's+**blocked**: Autodesk DPAPI-encrypts Fusion's on-disk token store+(`%LOCALAPPDATA%\Autodesk\Identity Services\idservices.db`, `products`/`mcptokens` tables)+**with app-specific entropy** → `CryptUnprotectData` fails `gle=13` (ERROR_INVALID_DATA). You+cannot extract/reuse Fusion's token without reverse-engineering Autodesk's entropy (fragile,+ToS-violating, and credential-extraction tooling we will not build). So the bridge runs its+OWN 3-legged **PKCE OAuth** (public client, NO client secret) → `fusion_aps_*` verbs. This is+final; don't re-investigate token reuse.++## The payment rules (HARD — non-negotiable)+The new APS portal gates app creation behind a developer hub + an APS **plan**, and even the+**Free tier requires a payment method "to verify identity."**+- ✅ **A credit card on file for IDENTITY VERIFICATION is acceptable.**+- ⛔ **A user (or John, or Adom) being CHARGED ANY MONEY is NEVER acceptable.** "It's insane+  to get charged just to search your own files."+- ⛔ Therefore the bridge **MUST monitor usage and HARD-CAP before the Free-tier limit is+  reached** — it must be *impossible* for a user to accidentally exceed the free allotment and+  incur a charge. Build the meter + cutoff in; fail closed (stop searching) before any paid+  usage. (TODO to verify + bake in: confirm whether Data Management search is in APS's+  always-free API set or consumes paid tokens; cap accordingly. Until verified, treat it as+  capped.)++## Team model — PER-ORG setup; within an org, one admin sets up for everyone (critical)+The unit of setup is the **organization/company**, NOT the whole Adom platform:+- **Each org that uses Adom sets up its OWN APS app + Free plan + APS Developer Hub, ONCE.**+  Why: each org has its own separate Autodesk cloud data, and each org should bear its own+  free-tier quota (one org's usage must not eat another's, and Adom must not foot every org's+  API quota). So the Client ID is **per-org**, configured via `fusion_aps_set_client_id` (or+  baked into that org's bridge deployment) — do NOT ship ONE global Client ID for all Adom+  platform users.+- **WITHIN one org**, though, it's the big win: ONE admin does the plan→dev-hub→app→Client-ID+  setup, and **every employee of that org** just runs `fusion_aps_signin` ONCE (their own+  Autodesk login + one OAuth consent) — **no card, no plan, no hub, no app setup** for them.+  The Client ID is a **public PKCE identifier (no secret)**, so it's safe to share among that+  org's users. API usage bills to that org's single **Free** plan.+- This is exactly why the setup must be AI-DRIVEN: every org's admin runs the SAME annoying+  flow once, so the AI should drive it end-to-end per org.+- **TWO different things both called "hub" — do NOT conflate them:**+  - The team's **data/Fusion hub** (e.g. "Adom", with a shared folder like **"Main"**) = the+    team's cloud FILE STORAGE — the data we search. Pre-existing; NEVER create or touch it.+  - An **"APS Developer Hub"** (e.g. "Adom APS") = a credential container that only holds the+    developer APP/Client ID. Holds ZERO files. Created once by the admin.+  - The developer hub does NOT limit what's searchable. 3-legged OAuth means the app reads+    everything the signed-in USER can access — including the team's existing shared data hub+    and folders. So search hits the real shared team files regardless of which dev hub the app+    lives in. (Almost every Adom user already shares an Autodesk cloud hub — search "just+    works" against it once they sign in.)+- Net: admin does plan→dev-hub→app→Client-ID ONCE; ship the Client ID as the bridge default;+  every user does one `fusion_aps_signin` and searches the shared team files fast.++## Ecosystem + automation requirement+- Must work for **ALL Adom users**, not just John.+- The whole setup — APS account, Free plan, developer hub, app registration, OAuth — is+  **annoying and complex, so it MUST be fully AI-DRIVEN** end-to-end. The user does at most+  two things: enter their own card (ID verification) and approve the OAuth consent. Everything+  else the AI drives (see the `fusion-aps-signin` skill for the browser-driving HOW).++## The recurring loop to STOP having+The trap (John has corrected it >3×): hit the APS card/plan gate → conclude "this is too+much, let's just use the free add-in search" → John reminds you the add-in search is garbage+(30+ min) and APS is the way and the card-for-ID is fine and we cap usage. **Do not enter+this loop.** APS is the path. The card is fine (ID only). We cap usage so nobody is charged.+Drive the setup with AI. Done.++Related: [[project_adom_desktop_fusion_bridge]], skill `fusion-aps-signin` (the setup HOW).