---
title: "View and edit spec files"
description: "Open spec files and their revisions, compare versions, edit a file by hand, handle edit conflicts and use the Trash Bin."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.myspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# View and edit spec files

Every spec file in a project keeps its 10 most recent revisions; when a new one
is saved, the oldest is removed. You can read any kept revision, compare two of
them, and, in an Edit session, change a file by hand.

## Open a spec file

The file explorer on the left of the project page and of every session lists
your spec files under **Specs**, grouped into folders.

- **Select a file's name** to open its latest revision in the viewer.
- **Select the arrow next to the name** to show the file's revisions. Each row
  shows the revision number (for example **Rev 3**) and when it was saved.
  The newest revision is marked with a coloured dot. Select a row to open that
  revision.
- Revisions saved by someone else show their avatar. Hover it to see who saved
  the revision, and whether the AI assistant wrote it.
- A number next to a file name is the count of open comment threads on it. See
  [Comments](/guides/comments/).

On a phone, tap a file name to open it, or double-tap it to show its revisions.

## Read a file in the viewer

The viewer opens over the page. Its toolbar has these controls:

| Control | What it does |
|---|---|
| **Find** | Searches this file only. See [Find text in a file](#find-text-in-a-file). |
| **Outline** | Lists the file's headings. Select one to jump to it. |
| **Preview** | Shows the file formatted, with tables, code blocks and Mermaid diagrams. |
| **Raw** | Shows the Markdown source with line numbers. |
| **Diff** | Compares this revision with another one. |
| **Copy** | Copies the revision's raw Markdown to your clipboard. |
| **Download** | Saves this revision as a file on your computer. |

The viewer remembers where you were reading. When you open the same revision
again in the same browser, it scrolls back to that point.

Press **Esc** to close the viewer. If the find bar is open, the first **Esc**
closes the find bar.

### Compare revisions

1. Open one of the two revisions you want to compare.
2. Select **Diff**. The toolbar shows **Comparing:** with the open revision on
   the left and a revision picker on the right. By default it compares with the
   revision just before.
3. Pick another revision to compare with, if you need to.
4. Use **Previous change** and **Next change** to step through the changes.

A file with a single revision shows "This is the only revision — no comparison
available." For very large files the viewer shows "Files are too large to
display an inline diff." Use **Raw** to read each revision instead.

### Find text in a file

Select **Find**, or press **Ctrl+F** while the viewer is open. Type your search
term, then:

- Press **Enter** for the next match and **Shift+Enter** for the previous one,
  or use **Next match** and **Previous match**.
- Turn on **Match case** to match upper and lower case exactly.
- Press **Esc** or select **Close find** to close the bar.

The search covers only the file in the viewer, not the chat or the file
explorer around it.

### Mermaid diagrams

In **Preview**, Mermaid code blocks are drawn as diagrams.

- **Click a diagram** to zoom. It opens in a full-window view.
- In that view, scroll to zoom and drag to pan. You can also press **+** and
  **-** to zoom, **0** to reset, or use the **−**, **+** and **Reset** buttons.
  On a phone, pinch to zoom.
- Press **Esc** or select **✕** to close the view.

If a diagram cannot be drawn, the viewer shows its source and the error
instead. If you opened the file from a session that is still in progress,
select **Fix mermaid diagram**: the
viewer closes and a request to fix the diagram appears in your message box,
with the error and the diagram code. It is not sent until you send it, so you
can review or change it first.

## Edit a file by hand

You can change a spec file yourself in an [Edit session](/guides/edit-sessions/)
that is still in progress. Completed and archived sessions are read-only.

Editing by hand needs **Write** access on the project. With **Read** access
there is no **Edit manually** button, but you can still open, compare and
download every file and revision. See
[Teams and project access](/guides/teams-and-project-access/).

1. **Open the editor**

   Select the pencil icon (**Edit manually**) next to a file in the explorer,
   or on a spec file card in the chat. The editor takes the place of the chat.
2. **Make your changes**

   Choose how to edit with the switch on the right of the editor toolbar:

   - **Rich Text**: edit the formatted text. The toolbar offers undo and redo,
     bold, italic, underline and lists.
   - **Source Mode**: edit the Markdown directly.
   - **Diff Mode**: see your unsaved changes next to the version you started from.
3. **Save**

   Select **Save** at the top of the page. MySpec saves your changes as a new
   revision, shows "Changes saved" and returns to the chat. Select **Cancel** to
   close the editor instead.

After you save, an **Edited manually** card appears in the chat, and the
assistant is told about your change so it can take it into account.

- **Save** is turned off while you have no changes, and while the assistant is
  working. The editor then shows "Saving is disabled while the assistant is
  working."
- For more room, select **Enter fullscreen** in the editor toolbar or press
  **Ctrl+Shift+F**. Press **Esc** or select **Exit fullscreen** to go back.
- If your organization has reached its storage limit, the save is refused and
  your text stays in the editor. See [Usage and limits](/guides/usage-and-limits/).

### Leaving with unsaved changes

If you send a message, switch to another file or select **Cancel** while you
have unsaved changes, MySpec asks what to do:

- **Save changes and proceed**
- **Discard changes and proceed**
- **Dismiss and back to editing**

### Find and replace

In the editor, select **Find and replace** in the toolbar or press **Ctrl+F**.

- Press **Enter** for the next match and **Shift+Enter** for the previous one.
- Type the new text in **Replace with**, then select **Replace** for the
  current match or **Replace all** (**Ctrl+Enter**) for every match.
- Replacing works in **Rich Text** and **Source Mode**. In **Diff Mode** you can
  search but not replace.

### When Rich Text cannot open a file

**Rich Text** reads the file as MDX, where `<` starts an HTML tag. Text such as
`<= 200ms` or `<id>` stops it from loading, and the editor shows
"Rich Text can't open this content".

Select **Fix automatically** to escape those characters. Code blocks are never
changed. The editor tells you how many places it repaired. Check them in
**Diff Mode** before you save. If something cannot be fixed automatically, edit
it in **Source Mode**.

## Edit alongside other people

Above the editor, a bar shows who else has the file open:

- **People viewing this file**, and people **Editing this file with unsaved
  changes**, marked with a pencil.
- **MySpec AI**, when the AI assistant is writing to the file. Hover it to see
  "The AI assistant is working on this file."

You count as editing only while you have unsaved changes. Opening the editor to
read does not.

The bar may also show "*Name* is editing this file." with an **Edit anyway**
link. Select **Edit anyway** to take over editing. This is a signal, not a
lock: it never stops you, or them, from saving. The other person keeps their
unsaved text and sees that you are now editing. If you both save, the second
save is stopped and that person chooses what to do, as described below.

For presence across a whole project, see [Working together](/guides/collaboration/).

### When the file changes while you edit

If someone else, or the AI assistant, saves the file while you have it open,
the bar shows "Rev *N* saved by *name*." or "This file has changed since you
opened it." Your text is not touched.

Select **Compare** to open **Compare with a saved revision**. It shows the
differences between a saved revision and your unsaved draft. Pick a revision at
the top of the panel, then choose one of these:

| Option | What happens |
|---|---|
| **Use this revision as my starting point, keep my text** | Your text stays in the editor. **Diff Mode** now shows how it differs from that revision, so you can merge before you save. |
| **Discard my changes and load this revision** | Your changes are dropped and the editor shows that revision. |
| **Close without changing anything** | Nothing changes. |

### Save conflicts

If someone saved a newer version after you opened the file, your save is
stopped and you see **This file changed while you were editing**. Your changes
are not saved yet, and nothing is lost. The dialog shows how their version
differs from yours. Choose:

| Option | What happens |
|---|---|
| **Keep editing and merge manually** | Their version becomes your starting point and your text stays in the editor. Combine the two using **Diff Mode**, then save. |
| **Overwrite with my version** | Your version is saved as the newest revision. Their version is kept as the revision before it. |
| **Discard my changes and load their version** | Your changes are dropped and the editor shows their version. |

### Recover unsaved changes

While you type, MySpec keeps a copy of your unsaved text in this browser. If
the page reloads or the tab closes before you save, the bar shows "You have
unsaved changes from *time*." the next time you open the file for editing in
the same browser.

- Select **Restore** to put that text back in the editor. Then save it.
- Select **Discard** to throw it away.

The copy stays in the browser where you typed it. It is never shared with
anyone and never becomes a revision until you save. A copy you do not come back
to within 14 days is removed, and very large files are not kept.

## Bring back older text

You can open any kept revision, but there is no one-click restore for a live
file. To go back to an earlier version:

1. Open the revision you want from the file's revision list.
2. Select **Copy** to copy its raw Markdown.
3. In an Edit session, open the file in the editor and switch to **Source Mode**.
4. Replace the content with what you copied, then select **Save**.

This saves the older text as a new revision. If the file already has 10
revisions, the oldest one is removed.

## Move a file to the Trash Bin

You can move spec files to the Trash Bin from the project page and from Edit
sessions. Moving a file to the Trash Bin, restoring it and deleting it
permanently need **Write** access on the project.

1. Select the trash icon next to the file in the explorer (**Move to Trash**).
   On a computer, the icon appears when you hover the file.
2. Confirm with **Move to Trash**.

The file leaves the **Specs** list and appears in the **Trash Bin** section at
the bottom of the explorer. That section only shows while it holds files. Each
file there says who moved it and when, for example "Trashed by Alice · 2 hours
ago", so you know whom to ask before you restore or delete it.

> **Comments on trashed files**
>
> Existing comment threads on a trashed file stay readable. They can still be
> resolved or reopened, and you can still edit or delete your own comments.
> Nobody can add new comments or replies until the file is restored. See
> [Comments](/guides/comments/).

### Restore or delete a trashed file

Select a file in the **Trash Bin** to open it in the viewer. The viewer then
has two extra buttons:

- **Restore**: puts the file back in the **Specs** list. You see "File restored."
- **Delete permanently**: asks you to confirm, then deletes the file. This
  cannot be undone.

> **Permanent means permanent**
>
> A permanently deleted file cannot be restored. Use **Restore** if there is
> any chance you still need the file.

Source: https://docs.myspec.dev/guides/spec-editor/index.mdx