docs/intent/04-surfaces/01-surface-principles.md

Surface Principles

Key Ideas

  • Surfaces Are Adapters: they expose model, workflow, process, and tools without owning their meaning.
  • Same Capability, Different Ergonomics: CLI, browser, API, desktop, and agent surfaces should differ by interaction style, not by product semantics.
  • Agent-First Direction: surfaces should increasingly support direct agent operation.
  • Human Accessibility: browser and desktop surfaces 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 capability access with little or no human-style UI.

The purpose of a surface is to make shared capability usable in a context, not to create a separate product.

Expected Role

Every surface should preserve the same underlying model and workflow semantics. If a Gap 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 shared 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 desktop modules. The browser and desktop are currently the richest human surfaces; 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 shared capabilities directly. The browser and desktop should still remain valuable for oversight, review, explanation, and manual intervention.