2. Project structure¶

Where things are, and where to add yours.

Layout¶

src/personal_os_setup/
  detect_os.py        OS / distro / WSL detection, builds the package list for this machine
  settings.py         ApplicationSettings (pydantic-settings) and the loguru logger
  frontend/           Textual TUI (app.py, dialogs.py, dotfiles_tree.py, main.py, app.tcss)
  tasks/              system actions and package managers (factory.py, managers/, system/)
  config/
    packages.yaml     the single source of truth for installable packages, per distro and manager
    chezmoi/          dotfiles source (.chezmoiroot points here)
    unix/ windows/ darwin/ others/ home assistant/   OS-specific config and scripts
tests/
  README.md           safe test map and validation boundaries
  unit/               frontend/, system/, release/, docs/, ci/ and core tests (parallel)
  skills/             isolated POSIX skill deployment scenarios
  integration/        make test-integration (CI only: installs real packages)
  archlinux/          manual interactive Arch sandbox (not a CachyOS integration pass)
docs/                 the documentation hub (OS guides, TV, home server, apps)
docs/developer/       this guide
scripts/              release.sh, vm.sh, docs generators, emoji_commit_parser.py
makefiles/            one .mk per concern, included by Makefile
.github/              workflows, composite actions, Renovate, issue and PR templates
.claude/skills/       repo skills for AI agents (also linked in .agents/skills)
install_unix.sh       one-line installer (Linux, WSL2, macOS)
install_windows.ps1   one-line installer (Windows)
properdocs.yml        documentation site (MkDocs Material)
CHANGELOG.md          written by semantic-release, never by hand

Where to add things¶

Task	Where	Help
a package	`src/personal_os_setup/config/packages.yaml`	—
a TUI action or package-manager backend	`tasks/` + `frontend/`	skill `add-system-action`
a dotfile	`src/personal_os_setup/config/chezmoi/`	skill `chezmoi-scripts`
a doc page	`docs/<topic>/`	skill `docs-site`
a setting	`settings.py`	Add a setting
an authored agent skill	`.claude/skills/<name>/` then `make skills-link`	skill `skill-layout`
a make target	`makefiles/<concern>.mk` with a `## description`	—

Add a setting¶

Add a field to ApplicationSettings in settings.py; it is read from the environment or .env.
Read it through the module-level settings object, never os.environ.
A secret is a SecretStr: read it with .get_secret_value().