Documentation

Your home folder

On most distros, your home directory accumulates Desktop / Documents / Downloads / Music / Pictures / Videos / Public / Templates as eight loose top-level folders. After six months it's a swamp: where did I save that PDF? Documents? Downloads? Desktop? Margine flips the question. Three top-level folders, each with a clear job. Your save dialogs, screenshot tool, and Nautilus sidebar already point at the right sub-folders by default. You don't configure anything; on first login margine-bootstrap creates the layout once and walks away.

The one-screen picture

Here's the entire tree. Three roots at the top. Everything else lives below.

~/                            ← your home

├── data/                  ← keep-forever stuff (back this up)
│   │
│   ├── personal/          ← Documents target. Your "my files".
│   ├── inbox/             ← scans, imports, things to sort
│   ├── media/
│   │   ├── photos/        ← Pictures target. Camera, screenshots.
│   │   ├── audio/         ← Music target.
│   │   └── video/         ← Videos target.
│   ├── projects/          ← active creative projects
│   ├── shared/            ← shared with other devices/users
│   └── templates/         ← Office / LibreOffice templates
│
├── dev/                   ← source code. Git repos, sandboxes.
│
└── scratch/               ← disposable. Delete without guilt.
    └── downloads/         ← Downloads target. Default save dir.

The rule, in one sentence

data is what you'd cry over losing. dev is code (already on GitHub anyway). scratch is trash with a delay.

What Margine wires up for you

None of this needs configuration. On first login the ujust margine-bootstrap step (which the autostart runs once) creates the folders, writes ~/.config/user-dirs.dirs, and registers the Nautilus sidebar bookmarks. Everything just points at the right place from then on.

Save dialogs (GTK/GNOME apps, Bazaar installs, Firefox/Zen downloads) default to ~/scratch/downloads/, not ~/Downloads. Downloads are ephemeral until proven otherwise: they land outside your backup, and you promote the keepers into ~/data yourself.
Screenshots (PrintScreen for the menu, Shift+PrintScreen for a region) land in ~/data/media/photos/.
GNOME SoundRecorder writes to ~/data/media/audio/.
"Documents", "Pictures", "Music", "Videos" in every Save-As dialog already resolve to the ~/data/<...> sub-folders below: the XDG key→path mapping in user-dirs.dirs handles that.
Nautilus sidebar shows nine bookmarks (Documents, Downloads, Pictures, Music, Videos, Shared, Projects, Development, Scratch) pointing at the corresponding folders inside data/ / dev/ / scratch/.

Why three roots and not the classic eight?

The eight XDG folders (~/Documents, ~/Downloads, …) are flat at the top level. After a few months you have also ~/Music, ~/Videos, ~/Templates, ~/Public, plus whatever apps drop there (~/snap/, ~/.local/, ~/Desktop/, …) and the distinction between "stuff I made" and "stuff some installer put here" disappears.

Margine groups by intent, not by file type:

Backup is one folder. Want to back up everything personal? rsync ~/data/ <target>. Done. You don't have to remember every individual XDG folder.
Moving to a new machine is one folder. Same logic.
Source code separated. rm -rf ~/dev/old-project never touches a single photo.
Scratch is fearless. ~/scratch/ exists so you can dump a 4 GB video export "just to see" and clear it next week without wondering if you needed it.

Where do I put X?

A photo I took, a song I bought, a video I shot
    → ~/data/media/{photos,audio,video}/

A PDF, a Word doc, a scan, anything I made or signed
    → ~/data/personal/

A file I downloaded (Bazaar install, Firefox dl, attachment)
    → ~/scratch/downloads/  (default; move the keepers into ~/data)

A project I'm actively working on (video edit, CAD job, photoshoot)
    → ~/data/projects/<project-name>/

A repo I cloned, or a sandbox I'm hacking in
    → ~/dev/<repo>/

A test export, a screen recording I'll delete, a random ISO
    → ~/scratch/

A file someone else on my LAN/another PC needs
    → ~/data/shared/

An Office template / LibreOffice template
    → ~/data/templates/

What if I'd rather have the classic Documents / Downloads / ... ?

Free will, and there is a command for it:

ujust margine-home-stock

It puts the machine back to the stock Linux layout every other GNOME distro gives you: ~/Documents, ~/Downloads, ~/Pictures, ~/Music, ~/Videos, ~/Desktop, ~/Templates, ~/Public, with the XDG keys pointing at them and Margine's entries removed from the Files sidebar (bookmarks you added yourself are kept).

It never touches your files. ~/data, ~/dev and ~/scratch stay exactly as they are, with everything in them: the command only changes where apps default to. When it finishes it lists what is still living in the old tree, so you can move what you want, when you want. Moving your files is not a decision a script should make for you.

It shows the full plan first and asks before writing anything; log out and back in afterwards so every app picks up the new folders. Changed your mind? ujust margine-bootstrap puts the Margine layout back.

Prefer to do it by hand? ~/.config/user-dirs.dirs is plain text: edit it and point the XDG keys wherever you like.

If you do customize it: run margine-validate-declared-state later to see a clear "drift" warning that you've moved away from the shipped spec. That's informational, not an error.

Resetting the layout

If something gets messed up (you accidentally deleted ~/data/inbox/, or you want to come back to the default after a hand-edit), just run:

ujust margine-bootstrap

It's idempotent. Existing files are left alone, missing folders are recreated, user-dirs.dirs and the Nautilus bookmarks are restored to the shipped values.