Directory Schema

The directory schema (config/schema.yaml) defines the target structure for an organized corpus. The planner reads it to determine destination paths. The schema is a versioned document — changes require a version bump and must be committed to version control before any files move.

Top-level structure

The default schema defines five primary categories and four operational directories:

corpus/
├── 01_work/
├── 02_personal/
├── 03_reference/
├── 04_creative/
├── 05_archive/
├── _inbox/
├── _unsorted/
├── _dupes/
└── _pre-org/

Numeric prefixes force lexicographic sort order in file browsers and terminal listings. Underscore-prefixed directories are operational — they separate staging from content and sort to the top.

Category directories

Each category in the schema defines a purpose, subdirectories, default sensitivity tier, and retention policy. The full default schema includes these categories:

Category	Description	Default Tier	Subdirectories
work	Professional and employment documents	2	projects, writing, presentations, reports, correspondence
financial	Tax returns, invoices, receipts, statements	2	tax, invoices, receipts, statements, budgets, investments, banking
legal	Contracts, agreements, NDAs	2	contracts, agreements, correspondence, court, property
medical	Medical records, prescriptions, lab results	1	records, insurance, prescriptions, lab-results
personal	Identity documents, certificates	1	identity, certificates, correspondence, education, household, family
media	Photos, videos, audio files	3	photos, videos, audio, screenshots
creative	Creative writing, design files	3	writing, design, projects
technical	Documentation, specs, manuals	3	documentation, specs, manuals, guides, datasheets
reference	Research, articles, standards	3	research, articles, standards, vendor, bookmarks
correspondence	Email exports, letters, memos	2	email, letters, memos
archive	Historical files, completed projects	3	—
uncategorized	Files that could not be classified	3	—

The classifier assigns each file a category. The planner maps that category to a directory using schema.yaml’s prefix_map and structure sections.

Schema design guidance

Numeric prefixes

Numeric prefixes (01_, 02_, etc.) are optional but recommended for top-level directories. They impose a stable sort order that does not depend on locale or filesystem.

Underscore prefix

Directories prefixed with _ are operational. They are managed by fialr, not by the user. They sort before numbered directories in most filesystems, which visually separates staging from content.

Operational directories

Directory	Purpose	Behavior
`_inbox`	Landing zone for new files awaiting triage	Watched by scheduled inventory. Files classified and routed.
`_unsorted`	Low-confidence files fialr could not classify	Requires manual classification or schema expansion.
`_dupes`	Non-canonical duplicate files staged for review	Populated by `dedup`. No auto-delete.
`_pre-org`	Snapshot of original directory structure before reorganization	Created by `organize --execute`. Preserves original layout for reference.

Schema evolution

The schema file carries a version field. The rules for changing the schema:

Bump the version before any files move under the new schema
Commit the schema change to version control before executing any operations against it
Schema migration history is tracked in the schema_meta table in SQLite

This ensures that the schema version at any point in history is recoverable, and that no files are moved under an uncommitted schema.

Exclusion system

fialr uses a four-layer exclusion system. Layers are evaluated in order; the first match excludes the file.

Layer 1: Hardcoded (never overridable)

These directories are excluded unconditionally. No configuration can include them.

Exclusion	Reason
`.git/`	Version control internals
`node_modules/`	Package dependencies
`.venv/`	Python virtual environment
`__pycache__/`	Python bytecode cache
`.ssh/`	SSH keys
`.gnupg/`	GPG keys
`.Trash/`	macOS trash
`.Spotlight-V100/`	macOS search index
`.fseventsd/`	macOS filesystem events
`.DS_Store`	macOS directory metadata
`$RECYCLE.BIN/`	Windows recycle bin
`System Volume Information/`	Windows system
Project roots	Detected by sentinel files

Project roots are detected by the presence of sentinel files: .git, package.json, Cargo.toml, go.mod, pyproject.toml, Makefile, CMakeLists.txt, .project, pom.xml, build.gradle.

Layer 2: Config directory excludes

Explicit paths listed in fialr.toml under [exclusions].directories:

[exclusions]
directories = ["backups/old", "vendor/legacy"]

Layer 3: Config pattern excludes

Glob patterns listed in fialr.toml under [exclusions].patterns:

[exclusions]
patterns = ["*.tmp", "*.log", "~$*"]

Layer 4: XATTR/sentinel opt-out

Individual files or directories can be excluded by:

Setting the com.fialr.exclude extended attribute (macOS) or user.fialr.exclude (Linux):

xattr -w com.fialr.exclude true ~/Documents/skip-this-file.pdf

Placing a .fialr-exclude sentinel file in a directory:

touch ~/Documents/vendor-assets/.fialr-exclude

Any directory containing .fialr-exclude is excluded along with all its contents.

Exclusion audit

Every excluded file is recorded in the manifest with:

The file path
The exclusion reason
The layer that triggered the exclusion (hardcoded, config_dir, config_pattern, sentinel)

Nothing is silently skipped. The exclusion record is available in manifest.json and in the job report.