Refine Hub
Refine 4.3.2
Design intent / Surfaces

Surface Principles

Key Ideas

  • Surfaces Are Adapters: they expose Model and Application behavior without owning product meaning or Infrastructure mechanisms.
  • Same Application, Different Ergonomics: CLI, browser, API, and agent surfaces should differ by interaction style, not by product semantics.
  • Agent-First Direction: surfaces should increasingly support direct agent operation.
  • Human Accessibility: the browser surface should make Refine usable by people who do not want to operate only through a terminal.
  • No Surface Monoculture: the system should not depend on one interface surviving forever.

Purpose

Surfaces exist so different actors can use Refine well. A person may need visual overview, command palette navigation, settings, logs, or review affordances. A CLI user may need reliable commands and JSON output. A future agent may need direct Application access with little or no human-style UI.

The purpose of a Surface is to adapt shared Application behavior to a context, not to create a separate product.

Expected Role

Every surface should preserve the same underlying model and workflow semantics. If a Goal cannot transition in the browser, it should not be secretly allowed by the CLI. If a Feature order matters in workflow, the UI should explain it rather than hide it.

Surfaces should:

  • call Application services or daemon routes,
  • expose state clearly,
  • avoid duplicating workflow logic,
  • make errors visible and recoverable,
  • route user-visible notices into durable activity or System surfaces when appropriate,
  • stay replaceable as AI-native interfaces improve.

The current implementation has CLI, web, web server/API, and MCP modules. The browser is currently the richest human surface; the CLI is the most reliable command surface; the API exists mainly as the local daemon contract that shared surfaces use.

Future Direction

Future surfaces may be voice, IDE-native, agent-native, MCP-style, terminal-first, or fully autonomous. Refine should be ready for that by keeping the system’s meaning below the surface layer.

The eventual dominant Surface may be no visible UI at all: an AI system reading intent, inspecting state, and operating the shared Application directly. The browser should still remain valuable for oversight, review, explanation, and manual intervention.