Welcome. Let's walk through this together.

01Personas — one tiny choice about how the app should feel

When you first open Yarrow, there's one small choice to make, and it's truly small — you can change your mind any time, nothing gets deleted, and there's no wrong answer. The choice is just: what kind of work are you mostly doing right now? That's your Persona. There are seven of them, all in one picker.

The seven choices, at a glance

Basic — for when you just want to write

Basic is what you'd hand to a friend who said, "I just want a quiet notebook, please." The right-hand toolbar shows only the essentials: a switch between reading and writing, an outline of the current note, your tags, a scratchpad, and settings. That's it. Every other Yarrow feature is still there — it's just not on the wall, like a tool you keep in the drawer instead of the workbench.

Default — the full Yarrow workshop

Default is what most people end up using, and it's what new workspaces start at. You get everything Basic has, plus the connections graph, the history scrubber, Scenarios, and Kits. The five tailored personas in the next lesson all sit on top of Default — they don't take anything away, they add a small tinted button group on the right rail for whatever kind of work you're doing.

A persona is a gentle leaning, not a locked door. Whichever one you pick, every feature is still one quick keyboard shortcut away.

02The five tailored personas — what kind of writing are you doing today?

The first two personas (Basic and Default) were about how much of the app is visible. The other five are about flavour. Each one sits on top of Default and gently nudges the right rail toward a specific kind of work — drafting a chapter, working through a research paper, keeping a recipe book, talking through a tough decision. A small group of tinted buttons appears, three or so, all picked to be useful for that kind of work.

You pick one tailored persona at a time, or skip them entirely by sticking with Default. All five share exactly the same notes, tags, scenarios, and history underneath — the persona is just the easier doorway in.

A persona isn't who you are. It's just what you're doing this week. Switch as the work changes — Yarrow doesn't keep score.

03How to switch — three ways, all painless

You have three options for switching personas, and they all work — pick whichever feels easier in the moment.

1. The search-driven palette in Settings

In 3.1 the Settings → Personas pane is a search-driven palette. Open it (⌘, on Mac, Ctrl , on Linux and Windows), and you'll see a search box, a small Recently used row at the top (up to four), and the seven personas underneath. Arrow keys move the cursor, Enter picks the one you want, Esc clears your search.

1. Press ⌘, / Ctrl , to open Settings.
2. Click the Personas tab.
3. Type the persona name (or two letters of it) and press Enter. Done.

2. The Persona Actions popover (new in 3.1)

Look at the bottom-right of the window — there's a small pill that says the current persona's name. Click it and an Obsidian-style command list pops up, filtered to whatever's useful for that persona. It has its own search box and arrow-key navigation. Two universal rows always sit at the bottom: Switch persona… (which jumps to the picker above) and Open command palette….

3. The command palette

Press ⌘K, type the persona name (just "writer" works), and press Enter. The rail rearranges right then. No menus, no scrolling — just a few keys and you're there.

04What's a scenario? (Let's start with a story.)

Picture this: you're planning a month in Europe. You've jotted down a few notes — flights, budget, where to stay, what to pack. They all hang together. They're parts of one trip.

Then a thought pops up: "what if we went solo instead of as a couple?" And you can already feel it — the flight note would shift, the budget would shift, the packing list would shift, half a dozen things at once. It's not one little change; it's a whole different version of the same trip.

Here's the thing: you don't want to throw away your couple's-trip notes. You're not committing to anything yet. You just want to hold both versions side by side for a while and see which one actually fits. That's exactly what a scenario is for.

A scenario is a named "what if?" — a parallel version of your notes you can write into freely, knowing the original is safe and sitting right next to it.

05Why would I bother with this?

Honestly? Because life rarely gives you one path at a time. Here are real reasons real people end up reaching for a scenario:

• Planning a trip two ways — going alone or with friends, doing it on a budget or splurging just this once.
• Drafting the same chapter twice — the same scene, but told from a different character's eyes, just to see which voice rings truer.
• Making a big life decision — laying out "if we moved to Seattle" as a real, fleshed-out set of notes about apartments, schools, jobs, costs, before deciding for real.
• Tinkering with a recipe — keeping the version your grandmother taught you, and also a version where you tried olive oil instead of butter.
• Thinking through a stuck problem — exploring a second approach without abandoning your first one, in case the second one falls apart.
• Weighing job offers — one scenario per offer, so the trade-offs sit side by side instead of swimming around in your head.

The thread that ties all of these together: several notes need to shift together, in a way that hangs together as a whole. A tag can't do that. A folder can't do that. What you actually need is a name for "the other version of this," and that's exactly what a scenario gives you.

06How do I see my scenarios?

Open the Scenarios pane from the right-side rail — the icon looks like a small branching tree. Once it's open, there's a tiny toggle at the top-right that flips between two views:

1. Graph (the default) — a calm left-to-right tree showing where each scenario branched off the main trunk.
2. Cards — a tidy vertical list, one card per scenario. Easier on the eyes when you've got more than a few.

Here's what one of those cards looks like:

That yellow line — "5 differ from main" — is one of the most useful little numbers Yarrow shows you. It's how many notes you've actually changed in this scenario compared to the main version. In other words, it's a quick read on "how far has my thinking moved here?" Five small shifts? Big rewrite? You can tell at a glance.

07Making your first scenario

1. Open the Scenarios pane.
2. Click + New scenario from main — or, if you want to branch off another scenario instead, click that one.
3. A small dialog asks, "What question is this asking?" Type whatever feels honest — something like If I rewrite from her POV or If we go in summer instead. There are no rules here.
4. Press Enter. Your new scenario shows up in the tree, branching off from where you started.

That's all there is to it. Nothing in your existing notes has changed — the new scenario starts as an empty space layered over its parent, and from this moment on, anything you write goes onto that new layer instead of the original. The original sits patiently underneath, waiting in case you need it back.

If you'd rather skip the click-around, you can start a scenario from your keyboard any time: ⌘⇧N on Mac, Ctrl⇧N on Linux and Windows. Yarrow uses whatever note you're looking at as the starting point.

08The little "also exists on…" line

One of the kindest small touches in Yarrow: when you open a note that has another version of itself living over on a different scenario, a small italic line shows up just under the date. It quietly says, "by the way, you wrote a different version of this note over here." Each scenario it mentions is a clickable chip:

If you read that strip out loud, it goes something like: "hey, this note you're reading — Flights to Madrid — also exists in two other versions, on solo-version and couples-luxury, and they're not the same as this one." If a scenario isn't on the strip, it just means the note is identical there, or doesn't exist there at all yet. No drama either way.

09Taking a peek at the other version

Curious what the other version says? Click any chip in that strip and a small floating window appears, anchored right next to where you clicked. Inside it: the same note's body, exactly as it reads on that other scenario. You don't lose your place — your current view stays right where it was.

From here, you can do three things: read it and just close the popover (press Esc or click anywhere outside it), or actually do something with what you've read. We'll get to those next.

10Liking the other version better — borrow it

If, while you're peeking, you find yourself thinking "oh, that one's actually better," you can take it. Click Borrow this whole version, confirm when Yarrow asks, and your current note's body is replaced with the one you were just reading. Your old version doesn't disappear — it slides quietly into history, where you can always go grab it back.

If you've used a tool like git, this is what would normally be called "merging." We named it borrow because that's much closer to what you're actually doing: you picked which version you liked, and you chose to put it in this spot. There are no merge conflicts, no symbols cluttering up your file, no decisions being made by the computer. The other scenario is left exactly as it was. Only this note, on this scenario, moves forward.

11Looking at both versions side by side

Sometimes a peek isn't enough — you want to see everything, every paragraph, every line that's different, both versions next to each other. That's what the Compare view is for. You can open it three ways:

• The Compare button in the toolbar.
• The Compare side-by-side button inside a peek popover.
• The command palette: ⌘K, then type "compare".

Once it's open, here's what you can do:

• Pick the two scenarios you want to compare on each side. Or, if you'd rather, pick two specific notes.
• Choose how the differences get shown: summary, track-changes, split, cards, or marginalia. They all show the same information; some people find one easier on the eyes than another. Try a couple; pick your favourite.
• If you like keyboard navigation:
  • j / k — move down or up through the changes, one chunk at a time.
  • ← / → — flip between the five different views.
  • Esc — close it when you're done.

12Drafts and scenarios — when to reach for which

These two tools sound similar, and they kind of are — both are ways of trying out a different version. The difference is one of scale. A scenario is for a whole world; a draft is for a single sentence's worth of indecision. Here's how that shakes out:

The draft tab strip is small and sits right above the note's title — easy to forget about until you need it:

13"I'm done thinking about this one for now" — set it aside

Sometimes a scenario served its purpose and you've moved on, but deleting it feels too final — what if you change your mind? Yarrow has a softer option for exactly this feeling: set it aside. It's the equivalent of putting a notebook on a high shelf instead of in the recycling.

1. Open the Scenarios pane and click the card for the scenario.
2. In the detail panel that opens on the right, click Set this scenario aside.
3. Confirm.

Nothing actually leaves your computer. All the notes are still there. All your edits, all the history, all of it. The scenario just shows up dimmed in the graph and cards view, with a small "set aside" label, so you can see at a glance that it's resting and not part of your active work right now.

Want it back? Click the same button again — it now says Bring it back — and you're right where you were. Always reversible. Nothing lost.

This is different from Delete, which actually does take a scenario out for good. The general rule: if there's any chance you'll want to look at it later, set aside. Reach for delete only when you're sure, and if you're not sure, you don't have to be.

14"Okay, I've decided" — making a scenario the real one

Picture this: you've been writing in solo-version for the last two weeks, and somewhere along the way it stopped feeling like a "what if" and started feeling like the actual plan. You don't want to keep mentally swapping between "what's in main" and "what's in this scenario" — you just want this one to be main.

That moment has its own button. From the scenario's detail panel, click Promote. Yarrow asks for a confirmation (because this one's a real decision), and then:

• Your scenario becomes the new trunk — the new main.
• Other scenarios that were branching from the old trunk gracefully re-anchor to the new one.
• The old trunk doesn't disappear. It stays in the graph, gently dimmed, like a scenario that's been set aside.

This is genuinely the moment Yarrow was built for. Read the button as: "I've thought about it. This is the version I'm going with."

15When you're ready to decide — the decision matrix

If you've been using scenarios for a real, weighty decision — which apartment, which job, which trip — there's a screen built specifically to help you compare them all at once and feel okay about choosing. It's called the Decision Matrix, and it tries to be the friendliest version of "let's pick" you've ever met.

Open it from the top of the Scenarios pane, or hit ⌘K and type "decision matrix". What you'll see is a grid: each row is a note, each column is a scenario. Star the notes that really matter to you — the things you can't compromise on. Then every cell in the grid tells you something useful at a glance:

The half-filled circle is the symbol that does the most work for you. It's the answer to a question you'd otherwise have to click around to find — "and has this version changed, or not?" Now, in one glance, you can see which scenarios actually shifted your packing list and which ones quietly left it alone.

16Wikilinks & backlinks — letting your notes find each other

The second big idea in Yarrow, after scenarios, is letting your notes link to each other by name. While you're writing, type two square brackets — [[ — and a small picker quietly appears right next to your cursor. Start typing the title of any note in your workspace, and when you see the one you want, press Enter to drop in the link. Done.

Three nice things happen the moment you do this, and you don't have to think about any of them:

• The link works both directions. If your "A weekend in Lisbon" note links to "Flights to Madrid," then "Flights to Madrid" automatically shows "A weekend in Lisbon" in its Backlinks panel on the right. You don't have to keep that in sync — Yarrow does it quietly for you.
• Renaming a note doesn't break anything. If you rename "Madrid" to "Madrid (April 2026)," every [[Madrid]] elsewhere in your workspace updates to point at the new name. No broken links, no manual cleanup.
• Hover to peek. Hover over any wikilink for a moment and a small preview pops up with the linked note's title and first few lines, so you can see what's there without leaving where you are.

Saying what kind of link it is

If you want to be more specific, you can label the kind of connection a link represents. Right-click any wikilink and you get four options: supports, challenges, came-from, or open-question. Each one shows up with its own colour and line style in the Connections graph — so when you zoom out and look at the whole web of your notes, you can see the shape of your thinking, not just a tangle of arrows.

17The selection toolbar — drag, then choose

New in 3.1: any time you drag to highlight some text in a note, a small floating bar appears just above the selection. Six buttons, each one short and obvious — Bold, Italic, Code, [[ ]], Highlight, and ??. Click one and the change applies to whatever you have selected. Esc dismisses the bar; clicking outside the selection does too.

This is just a faster version of moves you already had. Wrap-in-brackets-to-make-a-wikilink used to be right-click → Insert wikilink. Add bold used to be the keyboard shortcut. The toolbar puts them all together so you can keep your hand on the mouse when that feels easier.

If you prefer keyboard shortcuts, they all still work. The toolbar is just a polite alternative — nothing replaces what was already there.

18The / panel — insert anything without leaving the line

Also new in 3.1: type a forward slash (/) at the start of a line, or anywhere after whitespace, and a panel opens with a tidy list of things you can insert. Heading, callout, table, math, divider — the formatting moves. [[ ]], ![[ ]] (transclude), # (tag), ?? — the linking moves. Open the command palette, open the scratchpad, toggle focus mode, scrub through history — the app-level moves.

The panel is searchable. Type a couple of letters and the list filters. Arrow keys to navigate, Enter to pick, Esc to dismiss.

If you've used Notion or Obsidian's / menu before, this works the same way. If you haven't, the easiest way to learn it is to type / in a note right now and scroll through the list — most rows are one-word names that explain themselves.

19Open questions — what to do with the things you don't know yet

Writing is full of moments where you hit something you don't have answers to. A fact you need to look up later. A decision you're not ready to make. A name you'll invent in a different sitting. Most tools force you to either pause and figure it out, or write a TODO and lose track of it. Yarrow has a gentler answer: just type a literal ?? next to the thought, and keep going. Yarrow notices it and gathers it up for you as an open question.

The ?? shows up softly highlighted in the text, and every open question across your whole workspace is collected, automatically, into one place: the Open Questions pane on the right rail. Click any entry there to jump straight to the line in the note that asked it.

Think of ?? as a polite way of saying, "I don't know yet — I'll come back to this." The panel is your come-back-to list, doing the remembering so you don't have to.

If you've picked the Researcher persona, the rail gives you a small bonus: a one-click button that filters the open-questions list to just the note you're currently reading. Helpful when you're elbow-deep in one paper and you don't need to see questions from anywhere else.

20Tags — the gentlest way to organise

Tags are the most low-key tool Yarrow gives you. Anywhere in a note — the body, the YAML frontmatter, anywhere — type #tagname, and that's it. The tag is indexed. Click any tag inside the editor to filter your notes list to everything else that uses it.

Most tags are just whatever you decide to call them. But Yarrow does recognise seven special tag names as a kind of shared vocabulary, each with its own colour. The point isn't to be strict — it's so that everyone using Yarrow can read each other's notes. Your #review always means "this needs attention," in the same warm amber, in every note.

• Sensitive (#clinical / #private / #phi / #confidential) — rose. Yarrow keeps these notes out of autocomplete previews and search snippets, so private things don't peek out unexpectedly.
• Attention (#review / #followup / #todo / #wip) — amber. Things you'll come back to. The Clinician persona surfaces these in its Follow-ups list.
• Mature (#evergreen / #permanent / #canonical) — emerald. Notes you trust. "Settled thinking; safe to link to from anywhere."
• Question (#question / #q / #open) — cyan. Something you're genuinely asking, not telling.
• Decision (#decision / #decided / #resolved) — indigo. The kind of note you'll want to find again when someone asks "wait, why did we do it that way?" The Developer persona collects these into its Decision log.
• Draft (#draft / #sketch / #raw / #seedling) — faded italic yellow. Half-formed; not yet ready for other notes to lean on it.
• Archived (#archived / #dead / #deprecated) — struck-through grey. Old, kept for reference, no longer in use.

To see every tag you have, open the Tag Browser from the rail (the tag icon, between Outline and Kits). It lists every tag in your workspace with how many notes use it, and there's a small legend at the top in case you want a refresher on the seven special kinds.

21The inline glossary — your own vocabulary, underlined in place

Most of us have a small pile of words that come up over and over in our notes — proper nouns, project codenames, terms of art, characters in a story, ingredients in a kitchen vocabulary. In 3.1 you can teach Yarrow what they mean once, and from then on every occurrence of the term gets a subtle dotted underline. Hover the underline and the definition pops up. That's the inline glossary.

How to add a term

1. Open Settings (⌘, / Ctrl ,) and click the Glossary tab.
2. Type the term, type a definition, click Add term. (⌘/Ctrl+Enter in the definition field works too.)
3. That's it. Every note open in the editor re-highlights right away.

Each row in the list is editable in place — change the term, edit the definition, or click Remove. Edits commit when you click out of the field or press Enter.

How the matching works

• Case-insensitive. Defining shore matches Shore, SHORE, and so on.
• Word-boundary aware. Defining shore won't underline ashore or shoreline.
• Longest term wins. If you've defined both data and data structure, the longer phrase highlights as a unit.

Where the glossary lives

It's a single small file at .yarrow/glossary.json inside your workspace, tracked alongside your notes. That means your glossary travels with the workspace: if you sync to another machine, you'll see the same underlines and the same definitions there. There's nothing magical about the file — you can open it in any text editor if you want to bulk-edit or restore a backup; Yarrow re-reads it when you open the workspace.

22History — the part that quietly remembers everything

Whenever you pause writing for a few seconds, Yarrow tucks away a tiny snapshot of the note. These are called checkpoints, and the lovely part is that you do absolutely nothing to make them happen. No commit messages. No "save now?" prompts. No agonising about whether this version was good enough to keep. Yarrow just remembers.

When you want to look back, click the History icon on the rail (or hit ⌘K and type "history"). You can scrub through every past version of the note you're currently in.

• The left side is a timeline, gently grouped by recency — Today, Yesterday, This Week, Older.
• The right side shows the version your cursor is currently on, with the changes highlighted (additions in green, removals in red), so you can see what shifted.
• Use ↑ / ↓ (or j / k) to scrub through. Press Enter to restore that version.

Restoring an old version never deletes the version you have now. Yarrow just adds a new checkpoint with the older content on top — your timeline keeps moving forward, and your "current" version goes into history alongside everything else.

23The little cheat sheet

If you skim everything else, this is the page to keep. The vocabulary, the buttons, the keys.

24Questions you might be sitting with

If something's been quietly bugging you, this is where we try to answer it. Don't see your question here? It's a real one, and you can add it; we'd genuinely like to hear it.