docs(solutions): document solution start reachability and global_repo_access

[mlspivey]

What

Documents two behaviors of bifrost solution start that aren't currently written down anywhere: which routes the dev proxy serves itself versus proxies to the instance, and what global_repo_access actually does.

global_repo_access currently appears exactly once in the docs — as a field name in the bifrost.solution.yaml list in "One definition, many installs" — with no description of its effect.

Why

Working through a v1→v2 migration whose app calls workflows the Solution doesn't own, I hit the proxy's 404s and had no way to tell from the docs whether that was a scope problem, a permissions problem, or intended. The runtime error message names the flag and is genuinely helpful, but you only see it after the failure. Two details cost the most time:

• /api/profile and the /api/tables list proxy straight through, while document reads and non-local workflow execs do not. The app looks correctly wired right up until the first real data call, which sends you looking in the wrong place.
• The flag covers workflow resolution but not tables. Turning it on fixed every workflow and integration call at once and left the table 404s exactly as they were, which reads as a partial failure unless you know it's the intended boundary.

Verification

All claims tested against a live instance with a bound Solution install:

• Proxy vs. direct comparison for /api/tables/{t}/documents/count — same token, same ?scope=<install-id>: 404 through the proxy, {"count":33} direct. So the interception is the proxy's, not a scope or permission rule.
• 404 reproduced by table name and by id, with and without ?scope=.
• /api/tables (list) and /api/profile confirmed passing through unchanged.
• With global_repo_access: true, an instance-owned workflow executed successfully through the local origin and returned live third-party integration data — response carried a real execution_id and is_transient: false, versus solution-start-… / is_transient: true for a function in functions/.
• Token resolution order and the vite serve-only define read from the scaffold's vite.config.ts.

Deliberately not documented here: deploy-time validator behavior for this flag. I didn't test it and didn't want to assert it.

Note

solutions.md is mirrored byte-identically at plugins/bifrost/skills/… and .claude/skills/…; both are updated so they stay in sync.

[jackmusick]

Thanks for documenting the local-dev trust boundary—the no-sandbox warning, token-not-in-build distinction, and transient local workflow versus durable platform execution guidance are useful and should be retained.

The route/access matrix needs correction before merge, though. Verified against current code, existing tests, and a live bound Solution install:

• allow_global_repo_access is not workflow-code-only. api/src/services/solution_scope.py already gates table lookup and file read fallback. With the flag enabled, a Solution app read a global table by name; with it disabled, the same web-SDK request returned 404. Table policies still apply, and fallback tables are read-only.
• The generic solution start proxy does not locally serve/intercept table document routes. It forwards the request to the instance while adding the Solution scope/header contract. The observed proxy 404 is consistent with the bound install/flag/policy state, not a permanent table exclusion.
• Configs/integrations/OAuth/knowledge are shared services under their existing org/global authorization and are not governed by this flag. The live Solution workflow resolved config and integration values in both flag modes.
• Loose org/global workflow fallback is the part that was inconsistently enforced for deployed workflows; #527 fixes that and adds allowed/denied deploy-level tests. Sibling-Solution workflows remain inaccessible.

Please keep the accurate local-dev and portability material, but replace the workflow-only/table-404 claims and interception wording with the verified matrix in #527: #527. I opened that separately rather than modifying this contributor branch because the correction requires runtime enforcement and executable coverage, not only docs.