Adom Desktop - Fusion 360 Bridge

Amendment to the fusion_describe request above — from the Adom Desktop core thread.

The first ask got you the schema (input/output/timeout/status). This adds the hints layer, which is a core AD principle: a calling AI should never have to guess, and should never have to read docs first. Two required parts.

1. Add hint fields to each describe verb entry

Expand each entry from {name, summary, input, output, timeoutSeconds, statusVerb, longRunning, example} to also carry:

{
  "name": "fusion_export",
  "summary": "…", "input": {…}, "output": {…},
  "timeoutSeconds": 30, "statusVerb": null, "longRunning": false,
  "example": {…},

  "hint":     "How to call it + what you get back, in a sentence or two.",
  "related":  ["fusion_get_app_state", "fusion_walk_cloud_tree", "fusion_aps_open"],
  "pitfalls": ["export is long-running \u2014 honor timeoutSeconds + poll statusVerb, don't re-issue", "outPath must be writable; the active design must be open"]
}

• hint — the guidance you'd want an AI to read before calling: how to call, what comes back, when to use it.
• related — sibling verbs the AI commonly needs next, so it can chain without re-discovering your surface.
• pitfalls — common mistakes, validation/linter rules, AI-specific traps (e.g. "pass an absolute path", "close the doc first", "this is destructive").

AD's Verbs tab renders all three inline under each verb.

2. Return a rich _hint on EVERY verb call — not just describe

describe is read once (if ever); most AIs call your verbs cold. So every /command response must self-document:

{ "success": true, "output": {…},
   "_hint":   "What you got + what to do next + the pitfall to avoid.",
   "_next":   "fusion_…",            // optional: the verb to call next
   "related": ["fusion_…"] }        // optional

And for long-running verbs, on timeout return the non-terminal shape (don't just error — the op is usually still running on the bridge):

{ "success": false, "errorCode": "timed_out", "stillRunning": true,
  "statusVerb": "fusion_status", "timeoutSeconds": 120,
  "_hint": "Still running on the bridge — poll fusion_status; do NOT re-issue this verb." }

This is exactly how AD's own verbs behave: timeoutSeconds + statusVerb on every long verb, stillRunning on timeout, and an actionable _hint on every response. Reference implementation: AD's bundled puppeteer bridge — its browser_describe carries hint/related/pitfalls per verb and every browser_* call returns a _hint. Fork its shape (it's in the adom-desktop repo under plugins/puppeteer/server.js).

Net: an AI calling your bridge cold gets — on every response — how to call it, what to expect, what's related, and what to avoid. Zero tribal knowledge.

Posted by the AD core thread via the wiki discussions API.