Connecting Your Folder

Why there is no separate “create folder” option

ResearchOS works against a real folder on your disk, and Chrome's File System Access API can only ever open a folder you point it at. It cannot create a folder from the picker dialog (the OS picker blocks the parent locations a new-folder flow would need, even the Documents root). An earlier version of this screen had a separate “Create New Folder” card with a name field, but it dead-ended on that browser limitation. Connecting an existing ResearchOS folder and starting fresh both work the same way through the drop zone. You point at a folder that already exists on disk, and ResearchOS sets up its structure automatically the first time you connect it.

The page layout, at a glance

The screen is titled Connect your folder. On a first visit, three things share it.

• The drop zone in the center: a dashed-border card with the heading Drag your data folder here. Below a short divider sits the Browse for a folder button for users who prefer the OS picker. Connecting an existing ResearchOS folder and starting fresh both use this same zone.
• BeakerBot in the upper-right: a small sky-blue beaker mascot in idle pose (not waving). Below the mascot is a speech bubble with a brief nudge, plus a button labeled Take the 3-minute walkthrough. Skip past it entirely if you already know what you want to do.
• The credentials stamp in the bottom-right: a small badge that names the academic project this app grew out of (a UW-Madison Distinguished Research Fellowship). Pure authority signal; nothing to click.

Want to look around before committing a folder? The seeded fake yeast lab (browse it in the app, or download it as a real starter folder you can link) is accessible from the welcome page and via the /demo URL. See Demo Mode.

Starting fresh? Make an empty folder first

Because the picker can only open a folder that already exists, you make the folder yourself first. Do this with your normal file manager (Finder on Mac, Explorer on Windows) before you click Browse for a folder.

1. Open your file manager and make a new folder anywhere you like (Documents/ResearchOS works well). IMPORTANT: Chrome blocks the Desktop, Documents, and Downloads folders themselves, but a folder you make inside any of them works fine.
2. Name it something like ResearchOS.
3. Click Browse for a folder and select the folder you just made, not its top-level parent.

What you'll do

1. Connect the folder. You have two equivalent ways. Click Browse for a folder to open your operating system's folder picker, or drag a folder directly onto the drop zone. The zone highlights with a blue dashed border and the heading changes from “Drag your data folder here” to “Release to connect this folder” as you drag over it. Release to connect. Both paths work for an existing ResearchOS folder and for a brand-new empty one.
2. The browser asks for permission to read and write that folder. Click Allow. Chrome remembers the grant until you clear the site's data, so you won't get reprompted every time (you may see it once more after a browser restart).
3. ResearchOS initializes the folder structure (e.g., users/, lab/) the first time you link an empty folder, then shows the user-picker screen. After you pick or create a username, you land in the app and can start working right away.

The optional walkthrough modal

The Take the 3-minute walkthrough button on the connect screen opens a small 4-beat modal that introduces the app before you commit to connecting a folder. It is opt-in, not auto-fire. Brand-new users see the speech bubble's gentle nudge (“New here? It is strongly recommended to take a short onboarding walkthrough (3 minutes). Returning? Just take it from here.”), and returning users ignore it entirely. Here is what the four beats cover.

1. Welcome. BeakerBot waves and gives you a two-sentence pitch for ResearchOS. There is also a small heart easter egg if you click the mascot.
2. Data security. The core promise is that your data NEVER leaves your computer. No upload, no central server, no telemetry on your research. See Security for the full story.
3. Folder choice. Local (recommended for solo) or cloud-synced (for cross-device or multi-person lab). Local skips the next beat and closes the modal; cloud advances to beat 4.
4. Cloud provider. Picks the cloud you want to host the folder in (OneDrive, Google Drive, Dropbox, Box, iCloud) and links you to the per-provider setup guide. Closing the modal returns you to the connect screen; the folder connection itself still happens through the drop zone.

A small Skip link sits in the corner of every beat so you can bail back to the picker at any time. The modal does NOT write anything to disk and does NOT persist a “seen” flag; reopening it is a one-click decision you make each visit.

What gets created inside the folder

ResearchOS creates a simple tree the first time you connect.

your-folder/
└── users/
    ├── <your-username>/
    │   ├── projects/
    │   ├── tasks/
    │   ├── methods/
    │   ├── notes/
    │   ├── Images/
    │   └── ...more         ← a folder per data type
    ├── public/            ← shared methods & protocols
    └── lab/               ← shared funding accounts

That tree is trimmed for readability. Each kind of record (events, goals, dependencies, purchases, and a few others) gets its own subfolder under your username, plus small counter files ResearchOS uses to hand out IDs. You don't edit those by hand. Everything is plain JSON and plain image files, so you can back up the folder by copying it, version-control it with git, or open it in Finder / Explorer at any time.

Reconnecting later

After your first connect, ResearchOS remembers the folder handle via browser storage and reconnects to it silently whenever Chrome still holds the permission, so most return visits drop you straight back into your data with no picker and no extra click. When the start screen does appear for a returning user, it greets you with Welcome back and an Open your folder button that re-opens the picker on the same location. The browser may show a one-time permission prompt the first time you reconnect after a browser restart.

Setting up a shared lab folder

If multiple people in your lab should share one folder, put the folder inside OneDrive, Google Drive, Dropbox, or iCloud, and follow Shared Lab Accounts. The critical step is making sure the folder is always available offline on every member's laptop.