# Welcome to Folio

> Install Folio, open a folder as a workspace, and meet the views you use to model your domain and query it across sources.

Source: https://semvia.io/docs/quickstart/welcome-to-folio

In Folio you model the entities in your domain and the relationships between them, bind the domain model to databases, APIs, data lakes and spreadsheets, and query the graph that results.

## Install

1. [Download Folio](https://semvia.io/download) for your platform and install it.
2. Launch Folio. With no workspace open yet, it shows the **Open Workspace** dialog, which lists your folders.

## Open a workspace

A workspace is a folder. Any folder works, even an empty one.

1. In **Open Workspace**, pick a folder, or click **New Folder** to make one.
2. Click **Open**.

Folio adds these files to the folder:

- `sem.json`, the manifest that makes the workspace a package, when the folder has none.
- `.mcp.json`, with a `folio` entry an agent reads to find Folio's [Model Context Protocol](https://modelcontextprotocol.io/specification) (MCP) server, which agents connect to. Folio keeps any servers already listed there.
- `.folio/`, where Folio keeps the layout and the views you had open.

A Welcome tab opens. Pick a file in the Explorer to start editing.

## Finding your way around

The Folio window has four parts.

Figure: Folio with plants.ttl open in the Turtle Editor and split right into its Graph View, and a Terminal in the Bottom Panel. Four numbered outlines mark the Activity Bar (1), the Explorer listing fleet.ttl, plants.rq, plants.ttl, profile.ttl and sem.json (2), the Main Area (3) and the Bottom Panel (4).

1. **Activity Bar**: Opens the Explorer and the views.
2. **Explorer**: Shows the workspace folder as a tree.
3. **Main Area**: Where files open. Here it is split, with `plants.ttl` as [Turtle](https://www.w3.org/TR/turtle/) beside its Graph View.
4. **Bottom Panel**: Views you keep open under your work. Here, the Terminal.

### The Activity Bar

The list below runs down the Activity Bar from top to bottom. Hover over a button to see its name. Right-click any button from Packages to Terminal to move it up or down, or to **Remove from Quick Launch**. To put one back, open **Settings** from the **Manage** menu and add it under **Views**.

- **Explorer** — Shows or hides the [Explorer](https://semvia.io/docs/quickstart/welcome-to-folio#the-explorer). `⌘B` (`Ctrl+B` on Windows) does the same.
- **Packages** — The workspace's own package and the packages it depends on, with **Build Package**, **Publish Package** and **Add Dependency**.
- **Views** — Quick launch for views: a picker that opens any view by name, with the Activity Bar's views listed first.
- **Secrets** — The credentials your connections to APIs and databases sign in with, kept on this machine and never written into the workspace. [Add credentials](https://semvia.io/docs/federation/credentials) binds one.
- **Problems** — Opens [Problems](https://semvia.io/docs/quickstart/welcome-to-folio#problems) in the Bottom Panel.
- **Terminal** — A shell in the workspace folder, in the Bottom Panel. Each click opens another.
- **Collapse bottom panel** — At the foot of the bar. Hides the Bottom Panel, and shows it again when clicked a second time.
- **Manage** — A menu with **Command Palette**, **Settings**, **Plugins**, **Keyboard Shortcuts**, **About** and **Third-Party Licenses**. To change the color theme, open **Settings** and pick one under **Appearance**.

> **Shortcut.** The **Command Palette**, in the **Manage** menu or on `⇧⌘P` (`Ctrl+Shift+P` on Windows), finds any Folio command by name and runs it, including opening any view. `⌘P` (`Ctrl+P`) opens the same box to find a file instead, and typing `@` first searches settings.
>
> For example, with `plants.ttl` open, press `⇧⌘P`, type **graph** and choose **Open in Graph View**.

### The Explorer

The Explorer shows the workspace folder as a tree. Click a file to open it in the Main Area.

Figure: Folio's Explorer. The Activity Bar runs down the far left. The Files tree shows the plants folder holding fleet.ttl, plants.rq, plants.ttl, profile.ttl and sem.json, with plants.ttl open in the editor beside it.

Explorer with the `plants` workspace open.

The buttons above the tree and at its foot:

- **New file** — Creates a file.
- **New folder** — Creates a folder.
- **Delete** — Deletes what you've selected in the tree.
- **Collapse all** — Closes every open folder.
- **Workspace name** — At the foot of the Explorer. Switches to another workspace.
- **Open Workspace** — Beside the workspace name. Opens a folder as a new workspace.

Drag the Explorer's right edge to make it wider.

### Arranging views

You can collapse the Bottom Panel or split the Main Area.

Collapse

Figure: Folio with plants.ttl in the Main Area and the Terminal in the Bottom Panel. A green outline marks Collapse bottom panel at the foot of the Activity Bar.

Click **Collapse bottom panel** at the foot of the Activity Bar. The Main Area gets the full height, and the views in the Bottom Panel keep running. Click it again to bring them back. The green outline marks **Collapse bottom panel**.

Split

Figure: The plants.ttl tab's menu with Split Right open, offering Turtle Editor and Graph View. A green outline marks the Split Right menu.

Right-click a tab and choose **Split Right** or **Split Down**, then the view to open. **Split Right** → **Graph View** on `plants.ttl` gives the window at the top of this page. The green outline marks the **Split Right** menu.

## The Views

Each view shows your work a different way. Turtle Editor and Graph View display the same underlying file, here `plants.ttl`, as text, a form or a graph. The SPARQL Editor and Problems views work across the whole workspace.

Code

Figure: plants.ttl in the Turtle Editor, with Code selected in the Code | Form switch and Class Schema in the Profile menu. The file starts with its prefixes and the line that binds it to the Class Schema profile, then the Power plant class and its properties.

Form

Figure: plants.ttl with Form selected. Namespace and Vocabularies sit at the top. The plants card has empty Title and Description fields and shows Profile Class Schema. The Power plant card, marked Class Schema, shows Label Power plant, its Description and its Properties, starting with name, capacity (MW) and operator.

### Turtle Editor

A [Turtle](https://www.w3.org/TR/turtle/) file can be viewed as **Code** or a **Form**. **Code** shows the file as text, and **Form** shows a card for each resource, with a field for each property. `plants.ttl` holds the domain model, with a class for each kind of plant and for the things a plant refers to, such as the company that operates it. In Folio, a class is represented using [RDF Schema](https://www.w3.org/TR/rdf11-schema/) (RDFS) and the [Shapes Constraint Language](https://www.w3.org/TR/shacl/) (SHACL), two standards built on the [Resource Description Framework](https://www.w3.org/TR/rdf11-concepts/) (RDF), the standard format for graph data. RDFS names a class and the class it specializes, and SHACL lists its properties and the values each one allows. The `dct:conformsTo` line near the top binds the file to the **Class Schema** profile, the set of vocabularies and rules Folio checks the file against. See [Write Turtle](https://semvia.io/docs/authoring/turtle) and [Form view](https://semvia.io/docs/authoring/form-view).

Figure: plants.ttl in Graph View. Power plant, marked Class Schema, lists its instance properties, from capacity (MW) to point of interconnection. Solar installation and Nuclear plant each have a subClassOf edge to Power plant. Each lists Power plant's instance properties too, and Solar installation adds panel count. All three plant nodes have an operator edge to Company and a pointOfInterconnection edge to Grid connection, which has an agreement edge to Interconnection agreement.

Solar installation and Nuclear plant list the properties they inherit from Power plant under the [inherited-properties rule](https://semvia.io/docs/modeling/inference#inherited-properties), with an edge for each one that points to a class.

### Graph View

The same `plants.ttl`, drawn as a node for each resource, joined by edges labeled with their properties. Code, Form and Graph View are three views of one file.

Figure: plants.rq in the SPARQL Editor, selecting each plant's name and capacity, largest first. Results shows 3 rows with columns name and capacity: Riverbend Station 1100, Dry Lake Solar 250 and Desert Ridge Solar 240.

Each row is one plant described in `fleet.ttl`, with its capacity in megawatts.

### SPARQL Editor

A [SPARQL](https://www.w3.org/TR/sparql11-query/) query, saved in a `.rq` file, asks a question of all the data in the workspace at once. `plants.rq` asks for each plant's name and capacity, largest first. The plants themselves are described in `fleet.ttl`, beside the domain model. Click **Run** or press `⌘Enter` (`Ctrl+Enter` on Windows), and **Results** shows the answer as a table.

Figure: The Problems panel under plants.ttl reads No problems to report.

### Problems View

Lists every statement in the workspace that breaks a rule its file is checked against, grouped by file. The list updates as you edit, and clicking a problem opens its file. Every file in the workspace passes its checks, so the view reads **No problems to report**. [Model your first class](https://semvia.io/docs/quickstart/model-your-first-class) shows one flagged and fixed.

[Next: Connect your agent](https://semvia.io/docs/quickstart/connect-your-agent): Optional: let an agent read and write your workspace and query the graph it represents.
