singularity-forge/docs/product/SURFACE_CAPABILITIES.md

SF Product Surface Capabilities

This document defines the command and feature availability across SF's three product surfaces: CLI / Headless, TUI, and Web. It records intentional gaps so they are not mistaken for bugs.

Surface Definitions

Surface	Description	Primary Consumer
CLI / Headless	Non-interactive command-line interface and machine-surface protocol (sf headless).	Scripts, CI/CD, editor integrations, autonomous dispatch.
TUI	Interactive Terminal User Interface with dashboards, visualizers, and live overlays.	Developers working locally who prefer keyboard-driven interaction.
Web	Browser-based interface (Next.js) with panels, command surfaces, and visual tools.	Developers who prefer a GUI, remote access, or power-mode workflows.

Feature Matrix

Command / Feature	CLI / Headless	TUI	Web	Notes
/status	✅	✅	✅	Text in CLI/Headless; dashboard overlay in TUI; terminal or sf-status panel in Web.
/plan	✅	✅	❌ Intentional Gap	See Intentional Gaps below.
/run (/next, /autonomous)	✅	✅	❌ Intentional Gap	See Intentional Gaps below.
/steer	✅	✅	✅	Web exposes via sf-steer panel.
/undo	✅	✅	✅	Web exposes via sf-undo panel.
/history	✅	✅	✅	Web exposes via sf-history panel.
/doctor	✅	✅	✅	Web exposes via sf-doctor panel.
/forensics	✅	✅	✅	Web exposes via sf-forensics panel.
/skills	✅	✅	✅	Web exposes via sf-skill-health panel.
/capture	✅	✅	✅	Web exposes via sf-capture panel.
/triage	✅	✅	✅	Web exposes via sf-triage panel.
/inspect	✅	✅	✅	Web exposes via sf-inspect panel.
/hooks	✅	✅	✅	Web exposes via sf-hooks panel.
/cleanup	✅	✅	✅	Web exposes via sf-cleanup panel.
/export	✅	✅	✅	Web exposes via sf-export panel.
/queue	✅	✅	✅	Web exposes via sf-queue panel.
/visualize	✅	✅	✅	Web exposes via sf-visualize panel.
/prefs	✅	✅	✅	Web exposes via sf-prefs panel.
/config	✅	✅	✅	Web exposes via sf-config panel.
/mode	✅	✅	✅	Web exposes via sf-mode panel.
/model	✅	✅	✅	Web exposes via dedicated Model command surface.
/thinking	✅	✅	✅	Web exposes via dedicated Thinking command surface.
/git	✅	✅	✅	Web exposes via dedicated Git command surface.
/settings	✅	✅	✅	Web exposes via dedicated Settings command surface (general, recovery, auth, admin, experimental).
/resume	✅	✅	✅	Web exposes via dedicated Resume command surface.
/name	✅	✅	✅	Web exposes via dedicated Name command surface.
/fork	✅	✅	✅	Web exposes via dedicated Fork command surface.
/session	✅	✅	✅	Web exposes via dedicated Session command surface.
/compact	✅	✅	✅	Web exposes via dedicated Compact command surface.
/tasks	✅	✅	✅	Web exposes via Dashboard and Activity views.
/research	✅	✅	✅	Web terminal supports typing the command.
/implement	✅	✅	✅	Web terminal supports typing the command.

Intentional Gaps

/plan is not available as a first-class Web UI workflow

Why: The web UI uses a different, browser-native planning and execution model. Planning artifacts are promoted through CLI-first workflows (sf plan promote) that require filesystem access, Git operations, and markdown rendering pipelines that are optimized for terminal and editor surfaces. The web surface focuses on higher-level UI interactions (roadmap views, milestone explorers, visual planning tools) rather than raw slash-command promotion.

What web users do instead:

• Use the Roadmap and Milestone Explorer views to inspect and navigate planning state.
• Type /plan in the embedded terminal if needed; the command executes but the full promotion workflow is CLI-first.

/run (/next, /autonomous) is not available as a first-class Web UI workflow

Why: The web UI uses a different, browser-native execution model. Backend execution is managed via specific API routes and WebSocket/bridge communication rather than a /run command dispatch. The web surface prioritizes supervised, click-driven execution (e.g., Power Mode, action buttons, workflow steppers) over autonomous terminal-style dispatch.

What web users do instead:

• Use Power Mode for guided, step-by-step unit execution.
• Use Chat Mode for conversational task dispatch.
• Type /autonomous or /next in the embedded terminal if needed; execution proceeds via the PTY bridge.

Design Principle

Behavioral coherence, not visual parity.

Every surface must expose the same underlying state (via deriveState(), UOK diagnostics, and bridge data) but may present it through different interaction models. A gap is intentional only when the surface provides an equivalent or superior alternative workflow for the same user goal.

Verification

This matrix is verified against:

• src/resources/extensions/sf/commands/handlers/core.js — CLI/TUI status handler.
• src/resources/extensions/sf/commands/handlers/ops.js — CLI/TUI plan and run handlers.
• src/headless.ts — Headless status and execution entrypoints.
• web/components/sf/command-surface.tsx — Web command surface registry.
• web/lib/command-surface-contract.ts — Web command surface type definitions.
• web/components/sf/sidebar.tsx — Web navigation and exposed commands.

For the full behavioral audit, see .sf/milestones/M001-6377a4/slices/S04/VERIFICATION_MATRIX.md.