Welcome and First Launch

Welcome to Cocoa. This guide walks beside you through the whole app, in the order you will meet it: where your notes live, the window, the Library, your first note, formatting, highlighters, files, collections, study, search, settings, and what to do when something goes wrong. Nothing here assumes you already know where a button is.

What Cocoa is

Cocoa is a notes app for the Mac that looks and behaves like a paper notebook. Each note is a continuous, paginated document drawn on ruled paper. Folders hold notebooks the way a shelf holds binders. Colored highlighter pens mark words with meaning — a term, a formula, something that is on the exam — and everything you mark gathers into lists and, if you want, flashcards.

Under the hood a note is a plain Markdown file (.md) inside one folder you choose. You can open that folder in Finder at any time, copy it, back it up, or move it into iCloud Drive. Cocoa never hides your writing inside a database.

The first launch screen

The first time Cocoa opens there is nothing to show yet, so the whole left column becomes a welcome screen ①. It says: "Your notes are plain Markdown files kept together in one folder. The only decision is where that folder lives." The right side of the window shows an empty panel titled No Vault with a folder icon — that is normal until you make your choice.

You have three choices. Each card lists exactly what will happen when you click it, so nothing surprises you.

Choice 1 — Keep my notes in iCloud Drive

The left card ② is the highlighted choice. It explains: "They sync to every Mac signed in to your Apple Account, and Apple keeps a copy."

What happens when you click Use iCloud Drive (the large blue button at the bottom of the card):

1. A folder window opens, already inside your iCloud Drive.
2. At the bottom of that window, click Use This Folder.
3. Cocoa makes a folder called Cocoa there and keeps every note in it.
4. On another Mac, choose this same option and pick that Cocoa folder — the same notes appear.

If this Mac does not look signed in to iCloud, a note appears inside the card: "This Mac does not look signed in to iCloud. If the window that opens is not iCloud Drive, sign in under System Settings › Apple Account › iCloud — or keep your notes on this Mac for now."

Choice 2 — Keep my notes on this Mac

The right card ③ says: "Nothing leaves this computer. You can move the folder into iCloud Drive later, and Cocoa will follow it."

What happens when you click Use This Mac (the bordered button at the bottom of the card):

1. A folder window opens in your Documents folder.
2. Click Use This Folder.
3. Cocoa makes a folder called Cocoa there and keeps every note in it.

Choice 3 — I already have a Cocoa folder

Below the two cards is a link-style button ④: I already have a Cocoa folder — open it…. Click it when you are setting up a second Mac, or restoring from a backup. A folder chooser opens with the message "Choose a folder for your notes. Cocoa keeps them there as plain markdown files." Pick your existing folder and click Choose.

The footnote ⑤ reminds you: "Whichever you choose, the notes are ordinary files you can open in Finder. The search index and the daily backups stay on this Mac, outside that folder, so nothing but your notes is ever synced."

What happens next: reading the folder

As soon as a folder is chosen, Cocoa reads it. The right side of the window shows a spinner with the words Reading the folder…, then a live count such as 12 files checked · 4 notes found with the folder currently being read in small grey text underneath. Under the count is a Stop button.

• On a brand-new folder this takes well under a second.
• If you pointed Cocoa at a folder with thousands of unrelated files, click Stop. The folder stays chosen, and the panel then reads: "Indexing was cancelled. Choose a smaller folder, or rebuild the index from the Help menu."

The system-folder warning

If the folder you chose is your home folder, the Desktop, Downloads, Library, Applications, Movies, Music or Pictures folder, an alert appears titled That looks like a system folder. It explains that folders like Desktop and Downloads hold thousands of unrelated files and that Cocoa works best with a folder of its own. It offers two buttons:

• Use It Anyway — carries on with the folder you picked.
• Create a Notes Folder Instead — opens the Documents folder window so you can make a proper Cocoa folder.

When a folder cannot be opened

If anything goes wrong — the folder is not readable, or the path is not a folder at all — the right side shows Could Not Open That Folder with a warning triangle and the exact reason underneath (for example "Cocoa is not a folder."). Two buttons follow:

• Create My Notes Folder (blue) — makes a folder in Documents, the same way as Choice 2.
• Choose Another Folder… (link style) — opens the folder chooser again.

The Library appears

When reading finishes, the right side of the window becomes the Library: a grid of folders drawn as colored folders and notes drawn as small pages. On a brand-new folder it says Your Library is Empty — Make a folder for a subject — Biology, Accounting — then notes inside it. with two buttons, New Note and New Folder. Chapter 3 is all about the Library.

The tour, and this manual

The first time a folder is ready, a short guided tour starts in the main window and drives itself. The first card asks one thing: Take the tour, or Skip. From there it opens each screen in turn — the Library, your folder and its highlighters, a note, its files panel, the outline and the inspector, the folder's shelves, Write with AI — says so each time it moves, and lights up the control it is explaining while the card beside it tells you what it does. There is nothing to do but read; Next moves on, and Finish on the last step leaves you in the Library.

Three times the tour stops and waits for you: for a folder, for a highlighter pen inside it, and for a note. The folder and the note are made from the Library's New button, whose menu offers only the item the step asks for; the pen from the folder's Highlighters button. Whichever the step asks for stays lit while everything else in the window is switched off, and the tour goes on by itself the moment the thing exists.

• Skip the tour (top-right of the card) ends it. Nothing is lost; take it again any time.
• Next and Finish move on; Back returns to the previous step.
• When the tour changes screens, a notice such as "Opening a note" or "Showing the inspector" appears first, and a chip on the card shows where you are.

To take the tour again: Help › Take the Tour (⌃⌥⌘/), the ? toolbar button › Take the Tour, or the command palette (⇧⌘P): type "tour".

This manual is the long version, chapter by chapter. Open it from Help › User Guide (⌃⌘/), the ? toolbar button › User Guide, or the palette: type "guide". Buttons that read Try it inside a chapter act on the main window while this window stays open; Previous and Next at the bottom step through the chapters, and Done closes it.

A realistic start: one student, one semester

Maya is starting a semester with four courses and wants everything on her laptop and her desktop. On the welcome screen she clicks Use iCloud Drive, sees her iCloud Drive in the folder window, clicks Use This Folder, and a Cocoa folder is made. The Library appears, empty. At home, on the desktop Mac, she clicks I already have a Cocoa folder — open it…, picks the same Cocoa folder inside iCloud Drive, and her notes are there. The rest of this guide follows Maya as she builds her notebooks.

Summary

• Notes are plain Markdown files in one folder you choose.
• The first screen offers Use iCloud Drive, Use This Mac, or opening an existing Cocoa folder; each opens a folder window where you click Use This Folder.
• Reading the folder shows progress and a Stop button; errors appear as Could Not Open That Folder with the reason.
• The tour runs by itself once; replay it from Help › Take the Tour (⌃⌥⌘/). This manual is Help › User Guide (⌃⌘/).

Common mistakes

• Closing the folder window without clicking Use This Folder — nothing is created; simply choose again.
• Choosing the Desktop or Downloads folder — Cocoa warns you; pick Create a Notes Folder Instead.
• Expecting notes to sync after choosing Use This Mac — that choice keeps everything local; you can move the Cocoa folder into iCloud Drive later.
• Skipping the tour on the first step and then hunting for it — it is one item away, under Help › Take the Tour.

Best practices

• Use iCloud Drive if you write on more than one Mac; This Mac if you do not.
• Keep the folder named Cocoa, so I already have a Cocoa folder — open it… finds it at once on another Mac.
• Let the folder finish reading before you start; the first index is the slow one, and every later launch is quick.
• Take the whole tour once. It is three minutes and shows every screen. Three times it stops and waits for you — for a folder, a highlighter and a note — so nothing appears in your notes folder that you did not make yourself; the rest it does for you.

Keyboard shortcuts used

Related features to learn next

• Chapter 2, The Main Window — every part of the window the tour pointed at.
• Chapter 13, Import, Export, Backups and Sync — what iCloud Drive means day to day.
• Chapter 16, Troubleshooting and FAQ — when the folder will not open.