[UX] Add first-run onboarding for users without ontology expertise #313

Problem

Utopia does not currently provide a clear first-run journey for new users.

After registration, users are taken directly to an empty graph. The page mentions configuring a model and uploading documents, but it does not explain:

• what to do first;
• what happens after a document is uploaded;
• when search and chat become available;
• what the ontology does in Utopia;
• whether the ontology must be understood or edited before the product can be used.

The main navigation exposes Graph, Search, Chat, Library, Review, Ontology, Mappings, and Settings at the same level, without showing the order in which a new user should approach them.

As a result, users may successfully deploy Utopia but still fail to reach their first useful result. The product also appears to require ontology expertise even though its default ontology and automatic extension mechanisms are intended to let users get started without it.

Current experience

A typical first-run flow is:

1. Register an account.
2. Land on an empty graph.
3. See a text instruction to configure a model and upload documents.
4. Find the model settings and Library without direct guidance.
5. Upload a document without knowing what processing to expect or where the result will appear.
6. Encounter concepts such as classes, properties, signatures, and axioms without an introductory mental model.

The README covers deployment and model configuration, but does not provide an end-to-end product walkthrough.

Expected outcome

A user without ontology expertise should be able to reach their first useful result without reading external documentation or editing the ontology.

The product should communicate this minimal mental model in plain language:

An ontology is the vocabulary and set of rules Utopia uses to recognize people, organizations, events, and their relationships. The default ontology and automatic extension features can help you get started, so you usually do not need to edit it first.

Proposed scope

Add a dismissible and reopenable first-run checklist for new deployments and empty knowledge bases:

1. Configure and test a chat model.
2. Confirm the recommended starter ontology.
3. Upload a document or load sample data.
4. Show parsing and extraction progress.
5. Guide the user to view the graph, run a search, or ask their first question.
6. Introduce Review and ontology maintenance only when relevant.

Supporting changes should include:

• Direct “Configure model” and “Upload document” actions in the empty graph state.
• Connected empty states across Graph, Library, Search, and Chat.
• State-aware guidance for unconfigured, empty, processing, failed, and ready states.
• Role-aware actions:
  • administrators can perform configuration directly;
  • other users are told what is missing and whom to contact.
• An in-app Getting Started guide.
• Plain-language explanations of ontology, classes, relationships, and review.

Acceptance criteria

• A new administrator can configure a model and upload the first document without consulting external documentation.
• The UI communicates processing progress and the next available action.
• The user can reach their first graph result or cited answer without editing the ontology.
• The UI explains the purpose of the default ontology and makes it clear that ontology editing is optional during initial use.
• Every onboarding action links directly to the relevant screen.
• Users are not shown actions they do not have permission to perform.
• The onboarding flow can be dismissed and reopened.
• Completed onboarding does not continue to interrupt existing users.
• English and Chinese copy remain consistent.
• Key onboarding states and administrator/member paths are covered by tests.

Out of scope

• Teaching OWL, RDF, or ontology theory in depth.
• Redesigning the ontology editor.
• Adding new industry-specific ontology packs.
• Changing the existing extraction, reasoning, or ontology-governance behavior.