# Guide

## Key Ideas

- **Persistent Help Surface**: Guide should explain Refine without taking users out of the app.
- **Get Started And Reference**: setup guidance and browseable reference are different modes.
- **Field-Level Help**: settings and controls should link to relevant guidance where possible.
- **App-Scoped State**: Guide progress and context should follow the attached app.
- **Not A Wizard**: guidance should be an outline or panel, not a forced page-state workflow.

## Purpose

The Guide surface exists to help users configure and understand Refine in context. It should make setup, target-app attachment, settings, governance, guidance, and system concepts discoverable without turning the product into a tutorial.

It also helps future agents and maintainers see where the UI expects explanatory support.

## Expected Role

Guide should act as a persistent right-side panel that can open to relevant entries from labels, fields, empty states, and setup flows.

Current implementation details that matter to intent:

- Guide is part of the browser shell, not a standalone route only;
- Get Started and Reference are distinct information modes;
- Guide state is scoped by app;
- app add, switch, remove, and detach flows must avoid stale cross-app guidance state;
- settings labels should prefer field-level Guide links where explanation matters.

Guide should stay terse and actionable. It should explain just enough for users and agents to infer the next step.

## Future Direction

Future Guide behavior should become more adaptive. Agents may update guidance from discovered project facts, explain configuration decisions, or surface context-sensitive advice.

The Guide should remain an intent-preserving support layer: close to the UI, grounded in the project, and readable by humans and agents.