1. Setup¶

Prepare the app, development tools and documentation environment.

Prerequisites¶

Make, Bash, Git and uv on macOS, Linux or WSL2. If uv is missing, run make install-uv; use make update-uv to update an existing installation.

Install¶

git clone https://github.com/AmineDjeghri/personal-os-setup.git
cd personal-os-setup
make install-dev
make pre-commit   # static checks and hooks
make test-all     # tests
make docs-build   # strict documentation build

make check runs all three at once (and first warns if the Git hooks are missing).

This creates .venv, installs the development/docs tools and, in a Git checkout, the Git hooks, then validates the checkout. If dependency metadata changes, run uv lock before make install-dev; its --locked check requires an up-to-date uv.lock. Checks never install tools or hooks.

Run¶

make run

This starts the TUI. To use the personal-os-setup launcher with this clone, run ./install_unix.sh from it (or ./install_windows.ps1 in administrator PowerShell). The installer updates the existing clone.

Documentation site¶

make deploy-doc-local

Everyday commands¶

Command	Use
`make check`	The full local gate before a pull request
`make test-local`	Self-contained tests only
`make pre-commit`	Run the static hooks; `FILES="path/a path/b"` limits them to files
`make docs-build`	Strict documentation build
`make deploy-doc-local`	Preview the documentation site
`make clean`	Remove caches and temporary files
`make help`	List all targets

Optional environments and tools¶

Command	Use
`make install-prod`	Production dependencies only (installs uv first when missing)
`make install-tools`	Quality and docs tools without the application dependencies
`make install-release`	Packaging and release tools without the application dependencies
`make update-uv`	Update an existing uv installation
`make act`	Run GitHub Actions locally (`make install-act` first; needs Docker)

For publication, see release credentials.

Editor and agent rules¶

Select .venv/bin/python; mark src as Sources Root and tests as Test Sources Root. Follow .editorconfig for indentation and line endings, including CRLF for PowerShell files. Project skills live in .claude/skills/. Agent rules live in AGENTS.md; CLAUDE.md links to it for Claude Code. Edit AGENTS.md to update the shared instructions.

make help lists all targets. Next: Conventions and Testing.