Overview
The public existing DB demo shows the connector path with seeded Postgres/MySQL data and no login. The signed-in Sources wizard is where an approved Free beta, Builder Trial, or Builder account connects its own staging/local/read-only database.
Start read-only. Create a least-privilege source, test the connection, inspect schemas, import only selected tables/views, review fields suggested by configurable markers, bind trusted SESSION values, generate a read-only capability/workflow, and run a test prompt before adding proposal writeback.
Source setup is hard-capped with no overages: Free Controlled Beta allows 1 live-read external Postgres/MySQL source; Builder Trial and Builder Paid allow 3 during controlled beta.
Connection tests and schema inspections are rate-limited, so broken credentials or repeated retries fail closed instead of hammering the external database.
If the last connection test detects write/admin privileges, normal mapping import is blocked. Replace the credential with a least-privilege read-only user or safe views before continuing.
The public demo and signed-in wizard share the same connector-flow, database-kind selection, safe table mapping, column allow/deny, generated-contract preview, workflow playground, evidence, query-audit, proposal-diff, locked-state, and approval-boundary UI patterns so the mental model stays consistent before and after signup.
The first generator templates are Support ticket agent, Billing/revenue-risk agent, E-commerce order/refund agent, Contract-to-cash exception agent, and Generic read-only Q&A over selected tables. All start read-only and produce workflow/proposal artifacts without giving the model raw SQL or source credentials.
The wizard shows friendly summaries first and generated Synapsor syntax second. Step 7 includes a typed workflow graph builder with starter presets, a node palette, a canvas, an inspector, and validation summaries so users can see and edit the database-owned contract path before generating code. Advanced users can view the generated SQL and SDK examples, copy the selected artifact, and open the Browser Console with the generated capability selected.
The workflow graph is not a generic automation canvas. It models Synapsor governance nodes: trusted SESSION binding, selected external reads, capability execution, evidence collection, Synapsor review branches for external proposals, approval/writeback boundaries, replay checkpoints, and end state. The backend validates the graph again before storing the generated contract.
After a test run, the wizard renders readable evidence rows, query audit fingerprints, capability trace data, proposal state, replay/checkpoint summary, and the raw response envelope for debugging.
When proposal writeback is configured, the wizard can list proposal cards for the selected source. Approve marks a proposal ready_for_writeback for a trusted worker; reject/request changes leaves the external database unchanged.
Two credentials, two phases: the source connection remains read-only for governed reads. A separate backend worker that you run with your own write credential applies approved proposals only after review.
The workspace uses explicit setup states instead of vague pending/ok labels: live_read_ready, mapping_required, proposal_ready, writeback_not_configured, writeback_dry_run_required, writeback_enabled, cdc_private_preview, connection_failed, credentials_missing, and permission_error.
Empty states are safe by default: no source, source with no imported mappings, mappings without a generated contract, and live-read without proposal/writeback each explain the next action and link to the seeded demo or docs.
Proposal approval fails closed when writeback is not configured, dry-run/readiness evidence is missing, permissions are locked, or the proposal is already terminal. Reject/request-changes remains a review action and never mutates the external database.
Replay in the wizard reads stored evidence, query audit, proposal, workflow, and checkpoint state. It does not rerun external side effects unless a trusted worker explicitly performs a separate writeback action.
CDC is private preview only. It is not part of normal Builder Trial setup and should not be enabled for customer production data.
Step 1: choose a source
Pick Postgres or MySQL. Start with staging, local dev, a read-only replica, or safe views. Do not connect your most sensitive production database first.
Use a dedicated read-only user. The model never receives the source connection string, and stored credentials are redacted after submission.
Step 2: inspect and import safe mappings
The schema inspector shows tables/views, primary-key guesses, tenant-column candidates, fields suggested for review, and unsupported column types.
Select only the tables/views the agent workflow needs. Fields suggested by your review markers, such as password_hash, api_token, payment details, email, phone, address, private notes, and binary/blob fields, should be allowed or kept out explicitly before import.
Step 3: bind trusted session values
Tenant, principal, customer/order/ticket/invoice IDs, branch IDs, proposal IDs, and run IDs must come from backend auth/session state, not the model.
ARG values may come from user/model input, but HIDDEN and SESSION values define the trust boundary.
Step 4: generate and test the contract
The generator creates external mappings, an agent context, a read-only capability, optional proposal capability metadata, and an agent workflow artifact.
Use the no-code builder to name the context, capability, workflow, ARG value, hidden SESSION bindings, evidence mode, row limit, timeout, replay retention, and optional proposal boundary. The workflow graph next to the form shows how Synapsor will enforce the path.
Start with the neutral read-only generator unless you intentionally choose a proposal-with-approval, green-lane policy-approved writeback path, or review-required proposal path. The graph is a governance contract, not a generic automation tool: invalid proposal/writeback paths must fail validation instead of silently generating unsafe artifacts. The generated SQL remains the source of truth and can be copied or edited after the safe defaults are created.
Use Copy syntax to copy the selected generated file. Use Open in Browser Console to jump to the workspace console with the generated capability selected for a test invocation.
Run a test prompt and inspect the capability result, evidence rows, query audit fingerprints, capability trace, proposal state, replay/checkpoint summary, and approval/writeback boundary.
Step 4.5: read the setup state
The Sources wizard shows a plain-language state for the selected source. live_read_ready means the read-only path is usable through imported mappings. mapping_required means no tables/views are visible to agents yet. proposal_ready means a proposal exists and needs review. writeback_not_configured and writeback_dry_run_required mean approval stays disabled until the worker boundary is configured and verified.
connection_failed, credentials_missing, and permission_error fail closed. Fix credentials, network access, SSL, or read-only permissions before importing mappings or running capabilities. cdc_private_preview is an operator/dev-test state, not the normal customer path.
Step 5: add proposal writeback later
Proposal writeback is disabled by default until read-only behavior is reviewed. Risky writes should become evidence-backed proposals with primary-key and tenant guards.
The proposal cards show target table, operation, primary key, tenant guard, evidence, branch/proposal status, writeback mapping, dry-run/readiness state, and before/after diff. Approving a proposal marks it ready for a trusted worker/writeback path only when the mapping and dry-run/readiness checks are present; rejecting it requests changes and keeps the external database unchanged.
Synapsor Cloud does not give the model direct write access to your external database, and the workspace approval UI does not apply writeback by itself.
Workspace wizard path
The UI mirrors the safe connector flow: live-read first, proposal writeback later.
- source-of-truth rows
- ORM and migrations
- normal app writes
- backups and replicas
- operational ownership
- source metadata
- safe mappings
- allowed/denied columns
- SESSION/HIDDEN bindings
- context/capability/workflow
- evidence and query audit
- proposal review cards
- trusted worker boundary
Developer notes
- Use public demo mode for visitors; never show a real credential form there.
- Use signed-in setup mode for approved/trialing/paid users.
- Keep source setup read-only first.
- Require tenant/session binding unless explicitly single-tenant.
- Show generated syntax and SDK examples without requiring users to write them first.
- Use the graph builder for workflow shape, but rely on backend validation and generated SQL as the contract source of truth.
- Review proposal cards before approval; trusted workers apply approved writeback separately.
- Keep CDC marked private preview only.