Settings

Key Ideas

• Settings Are Operational Context: settings determine how Refine works, not just how it looks.
• Domain Placement: controls should live with the feature domain they affect.
• Detached Safe: settings should handle no-app and app-switch states explicitly.
• Scoped Loading: settings surfaces should fetch only the data needed for the active tab.
• Guide Connected: settings fields should connect to guidance where users need explanation.

Process management lives on the main Control screen. Settings opens Nodes and contains configuration tabs.

Purpose

Settings exist to configure Refine’s relationship to the project, node, target app, agents, runtime, Skills, reporters, and performance.

They should help users make Refine work correctly in their environment without requiring deep knowledge of the internal implementation.

Expected Role

Settings consolidates the former Node and Governance navigation entries under /#/settings/<tab>. Workflow brings all Goal steps and their hooks, system events, custom actions, assigned Skills, and prompt Templates into one Settings tab. Skills and Templates remain shared resources with their existing storage and editing rules; Events remain the internal execution model. Governance and Quality remain workflow steps; their instructions are configured as Skills. Retired configuration routes redirect to Settings without retaining competing editors.

The tab order is Nodes, Reporters, Prompts, Hubs, Target App, and Runtime. Processes is the Main → Control screen; old Processes routes redirect there. Release work is configured as a Custom Skill, with no separate development tab.

Current implementation details that matter to intent:

• settings render through shared renderSettingsSurface flows;
• settings data loads are scoped by active surface and tab;
• detached mode short-circuits app-scoped calls and keeps app management actionable;
• target-app settings, runtime settings, reporters, Skills, processes, and performance are separate concerns;
• Runtime presents a blank parallel-run cap as Automatic. Automatic admission applies the node’s resource-budget percentage to both detected logical CPU cores and currently available memory; the default is 70 percent, leaving 30 percent for shared-host work. Entering a positive parallel-run cap is an explicit absolute node-level override. Unset node, provider, and target-app limits inherit the resulting global limit;
• node runtime settings include a validated state-sync stale threshold. Its default is longer than the normal remote-fetch cadence so routine scheduling jitter does not degrade health;
• the Nodes view keeps fleet bootstrap health separate from state-sync health: the active node uses this daemon’s evidence and other nodes remain unknown without direct evidence;
• Detail tables, including Skill history modals and Hub lists, open details through row clicks and Enter or Space, with visible keyboard focus. Separate destructive or inline input controls retain their own actions.
• Skills use plain labels and clickable rows with keyboard activation. Each row shows its trigger and has a Status toggle that saves enabled state without opening the editor, preserving the trigger and refreshing manual discovery. Conflicting writes refresh the current configuration;
• the Skill modal, including Governance, uses the shared Instructions and Settings tabs, opening on Instructions. Instructions retain rendered Markdown and editing; Settings contains all configuration controls. Tab switches preserve drafts and support keyboard navigation, and validation opens the tab containing the invalid field. Its title names the Skill. Trigger, Scope, and Status share a responsive row;
• editors reuse shared modal, input, table, and segmented styles. Parameter choices appear only for choice parameters, and new Skills have no Delete action;
• a Skill and its trigger save atomically under the shared configuration revision. Editors retain drafts after a conflict. Node switches fence submissions and preserve or explicitly discard unsaved drafts;
• Custom Skills are standalone actions in the selected project. Browser launches never inherit an open Goal. Launch forms collect typed parameters and defaults, then open the selected Skill in an agent tab with normal transcript, reconnect, and stop controls. Headless execution history retains findings, errors, process evidence, and cancellation;
• Guide icons and guidance surfaces are expected to help explain fields.

Settings should avoid overfetching and avoid hiding invalid states. If Refine is detached, paused, misconfigured, or missing a target app command, the settings surface should make that clear.

Future Direction

Future settings should become more inferential. Agents should be able to inspect the project, propose target-app lifecycle instructions and deterministic checks, explain tradeoffs, and safely update configuration with evidence.

The surface should move toward guided configuration and reviewable changes, not a growing form full of disconnected knobs.

Runtime AI providers

Runtime separates AI provider for this node from Shared AI providers. The node selector includes Use system default. Shared definitions expose a stable ID, display name, executable, ordered JSON argument arrays, automated and interactive modes, and advanced transport, session, and output settings. Provider drafts survive Runtime refreshes and failed saves; catalog revisions prevent overwriting another editor’s changes. Installation and authentication remain host responsibilities. See Configure AI providers.