The Garden Today

A garden is the set of files that describe one machine — how it’s configured, what’s installed, why each choice was made, what broke and how it got fixed. Most people scatter that across dotfile repos, wiki pages, shell history, and memory. soft-fig treats it as one first-class object with a shape a person or an LLM can navigate without being told.

This page is about the idea and its current reality. For the rules a garden follows, see Conventions; for the bigger picture, see the Vision & Roadmap.

One machine, described in place

A garden documents the device it lives on, and only that device. It is a tree of small, semantically-named directories — packages/pacman/, services/network/, hardware/ — each holding a CLAUDE.md that says what the directory is and a handful of reserved-name files that mean the same thing in every folder.

You get one garden per machine. Cloning the program to a new device moves the schema — the empty concept folders and the conventions — never another device’s content. Each garden is a standalone account of its own hardware, its own quirks, its own history.

What makes it a garden

Four properties separate a garden from a pile of notes.

The layout is the schema

There is no database and no front-matter taxonomy to learn. Knowledge lives in concept folders, and the reserved filenames carry the meaning: CLAUDE.md is “what this dir is and how to behave here,” notes/ holds device-specific quirks, troubleshooting/ holds fixes you’ll need again. Because the names are predictable, navigation is too — you (and Claude) always know where to look. The full set is in Conventions and, exhaustively, in the garden schema reference.

Commentary, not copies

When a real file outside the garden is the source of truth — /etc/pacman.conf, a systemd unit, a dotfile manager’s source — the garden does not copy it. It stores the commentary: why the choice was made, what was tried, what to watch for when it breaks again, under a Last reviewed: date so staleness is visible. A copy rots silently; commentary with a review date tells you when to distrust it.

History is part of the value

Nothing is deleted. Things that age out are archived, not thrown away — an abandoned project, an obsolete decision, and the reasoning that led to a replaced setup are all worth keeping. Underneath, every change is a typed, signed commit you can query by intent, so “what decisions did I make this month” and “everything that ever touched this project” are answerable questions. This history is managed by soft-fig itself, not git; see The Codebase → VCS.

Encrypted at rest, plaintext on demand

The on-disk store is ciphertext. The working tree you read and edit is a FUSE mount the daemon serves only while the garden is unlocked. Secrets can be sealed even within that otherwise-plaintext view — a whole file or an inline <vault> region — so an assistant reading the garden never sees them. Two layers, two threat models; the details are in Guides → Secrets and Reference → Crypto.

Opened from the root, read by Claude

The intended way to work in a garden is to open Claude Code from the garden root. The root CLAUDE.md is always in context and acts as the map; the per-directory CLAUDE.md files load on demand as Claude routes to them. This is the practice the whole layout is built around — it gets its own page in Working with Claude.

Where the project stands

soft-fig is 1.0.0 alpha software: single author, and its cryptography has not been independently audited (see the security policy). It has run as one person’s real Arch laptop garden for long enough to prove the idea out, and these docs keep the seam between what works and what is planned visible.

Built and working today:

• the Vault (encryption at rest plus selective, in-view secrets, with a declared recovery policy) and the integrated VCS (content-addressed ciphertext, signed commits);
• the daemon, the FUSE plaintext view, and the file watcher;
• softfig onboard, the first-run wizard that scaffolds a fresh garden;
• the agent and human surfaces: the MCP write verbs (including surgical edits such as patch_file) and the softfig-tui terminal UI;
• device pairing, replica backup and shared subtrees between your own devices, early but merged;
• the static deploy step (softfig deploy), the first slice of the dotfile-manager pillar;
• growlight, the autonomous work loop, run by the growlightd daemon.

Planned, not built: template rendering for deploy, a general desktop GUI, prebuilt binaries and distro packages (you build from source today), and the guided and plugin layers. The Vision & Roadmap has the full split, and The Codebase → Status tracks the code. The source repository is the source of truth.