Frontend Development

Ownership

The frontend presents backend-owned state and submits typed user intent. It does not invent task identifiers, infer authorization, or become the canonical owner of lifecycle state.

Add a Product Route

1. Keep the organization ID in the route and query scope.
2. Define typed loader/query behavior.
3. Render loading, empty, partial, failure, and success states.
4. Keep mutations explicit and refresh or reconcile affected data.
5. Preserve actionable backend validation messages without leaking raw internal errors.
6. Add route and helper tests.

Extend Integration Management

Managed provider name, description, URLs, icon, setup Markdown, categories, departments, and grants should remain catalog-driven. Registry cards are summaries only: logo, name, two-line description, readiness, and one contextual action. Provider management belongs in the shared sheet so connection, access, tools, Context, lifecycle actions, and unsaved-work handling stay consistent.

Keep the stable integration key and active sheet section in validated route search. Fetch the selected integration independently of filtered or paginated card results, and exclude section-only state from list loader dependencies. Browser history must be able to close and reopen the sheet without losing registry filters.

Compose provider-specific panels into the sheet rather than adding another overlay or a generic configuration framework. Every editable panel reports dirty and pending state. Search-only UI stays transient; pending submission locks navigation and lifecycle actions; dirty navigation goes through one discard confirmation. Initialize drafts from the canonical integration projection before reporting state so opening a clean panel never creates a transient dirty snapshot. Keep lifecycle actions in Connection and filter tool search by stable tool names rather than provider prose. Keep large MCP inventories in the connected-only Tools section, with search and bulk-selection controls outside the scrolling inventory. Discover lazily on first entry, retain the panel while the sheet remains open, and deduplicate development effect replay. Visibility refreshes may refresh the route projection, but they must not repeat provider discovery unless the integration ID, persisted revision, permission mode, explicit tool snapshot, or an explicit retry changed.

Onboarding uses the same redacted integration projection. Render that loader result directly and refresh it when the setup tab becomes visible again; do not copy it into component state that can remain stale after a separate connection or authorization flow.

OAuth providers usually need:

• service selection;
• connect and callback states;
• redacted identity;
• missing-scope handling;
• same-account reauthorization; and
• disconnect confirmation.

Human Inbox

Keep Questions, Approvals, and Reconciliation visibly distinct. A user should know whether they are providing information, authorizing a future effect, or recording the result of a possibly completed effect.

Context Rendering

Render source Markdown through the safe product boundary, preview PDFs without treating them as trusted executable content, and keep citations linked to retained source identity.

Product Theme

Use the shared Oblive color language: Geist, neutral surfaces, green primary, restrained shadows, and accessible light/dark states. This documentation site mirrors those tokens without importing frontend CSS directly.

Documentation Impact

When UI changes alter a documented flow, replace the affected screenshot and update the operator steps in the same commit.