docs: workspaces, SQL readings, and Execute review

[cursor]

Weekly documentation pass (cron) against source as of 0.2.334. No product-code changes.

Docs added/updated

• USER_GUIDE.md — new Workspaces section; Execute conflict review; SQL priced by destination dialect; troubleshooting for connections that “disappeared” after a switch.
• ARCHITECTURE.md — request scoping (WorkspaceScope, 404 not 403), install vs workspace permissions, sql-text tokenizer + dialect readings, Execute gate.
• CODE_MAP.md, CONTRIBUTING.md, DEPLOYMENT.md (FOX_ADMIN_POLICY), UNRELEASED.md, FEATURE-MODULE-GUIDE.md (status: built).

Codepaths covered

• Workspaces: platform/workspaces, /api/workspaces, effectivePermissions, Admin → Workspaces (join to open).
• SQL text: sql-tokens.ts / sql-readings.ts / sqlStatementCategories; /sql/execute prices fences as comments the database sees (refactor(sql): the keyword-scan stripper reads the shared tokenizer #517–fix(sql): price a code fence as the comments the database sees #522).
• Compare Execute: executeGate.ts / executeClick (fix(compare): Execute opens the review for a narrowing or missing-FK conflict instead of deploying #515) — missing FK and unacked narrowing open review instead of deploying.

Knowledge gaps addressed

Team workspaces (#491–#497) had no user or operator guide. sql-text was still “statement splitting and templating” after the shared tokenizer. Execute’s missing-FK / narrowing click was undocumented.

  

---

Note

Low Risk
Markdown-only changes; no runtime, security, or data-path modifications.

Overview
Documentation-only weekly pass (no application code): brings user, architecture, and contributor docs in line with shipped behavior around team workspaces, shared SQL lexing, and Compare Execute gating.

Workspaces — New/expanded coverage in USER_GUIDE.md, ARCHITECTURE.md, DEPLOYMENT.md, and CODE_MAP.md: workspace-scoped data (connections, secrets, runs), personal vs shared workspaces, invites/public join, admin list-and-join-only, WorkspaceScope / scopeOf(req), install vs workspace permissions, and FOX_ADMIN_POLICY. Contributor notes point to route-doubles.ts for route tests.

SQL text — Docs now describe packages/sql/src/modules/sql-text/ as a single tokenizer + per-dialect readings (not a second scanner); permission gates and classifiers must pass the destination dialect. Dialect checklist adds a sql-readings.ts step.

Compare Execute — Documents executeGate.ts: missing FK / unacknowledged narrowing keeps Execute clickable but routes the click to review; other blockers still disable the button.

Also updates UNRELEASED.md release notes, FEATURE-MODULE-GUIDE.md status (built), and terminology (left-rail views vs workspaces).

^{Reviewed by Cursor Bugbot for commit dcf3c6d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 30826268-d793-4219-9feb-1d276b89c6ac)