{
  "markdown": "# Modern Dotfiles\n\n[![CI](https://github.com/brunogama/dotfiles/actions/workflows/ci.yml/badge.svg)](https://github.com/brunogama/dotfiles/actions/workflows/ci.yml)\n\nA Nix-first, macOS-oriented home-environment configuration for a reproducible developer setup. It combines Home Manager and optional nix-darwin activation with shell configuration, safe convention-based linking, credential utilities, Git helpers, and local synchronization tools.\n\n> [!IMPORTANT]\n> This repository is configured for macOS hosts. Before activating it on another machine, review and personalize [`nix/host.nix`](nix/host.nix), which defines the account, host, architecture, and Git identity used by the Nix configuration.\n\n---\n\n## Highlights\n\n- **Declarative setup** - Nix flakes and Home Manager manage the primary user environment, with optional nix-darwin system settings.\n- **Explicit ownership** - Home Manager owns its declared paths; the convention linker manages eligible files and public commands outside that boundary.\n- **Safe activation** - Dry-run modes, collision protection, confirmations, and `pre-nix` backups avoid silently overwriting configuration.\n- **Productive shell** - Zsh, Starship, version-manager support, work and personal profiles, and shell-maintenance commands are included.\n- **Credential tooling** - Keychain-backed API-key helpers and encrypted credential-file workflows keep secrets out of the repository and shell history.\n- **Built-in quality checks** - Shell, Python, Nix, integration, and repository validation tooling support safe changes.\n\n---\n\n## Get started\n\n### Recommended: smart installation\n\nClone the repository, then preview the installation plan before applying it:\n\n```bash\ngit clone https://github.com/brunogama/dotfiles.git ~/.dotfiles\ncd ~/.dotfiles\n./install --dry-run\n./install\n```\n\n`./install` never fetches or synchronizes the checkout. It uses the current worktree contents, warns when they are dirty, and is safe to rerun.\n\n- On macOS, it selects the user-only Nix and Home Manager flow, bootstrapping upstream Nix with consent when required.\n- On Linux, it selects the retained legacy installer and provisions minimal prerequisites through `apt-get`, `dnf`, or `pacman`.\n- Unsupported platforms fail with an actionable error.\n\nFor the optional privileged macOS configuration, preview first and then apply it:\n\n```bash\n./install --system --dry-run\n./install --system\n```\n\n> [!TIP]\n> Use `--backend auto|nix|legacy` to choose a backend explicitly. `--nix` remains a compatibility alias, and `--legacy` is a shorter legacy alias. Pass `--username NAME` or `--machine-name NAME` only when changing host identity. Use `--nix-distribution determinate` for an existing Determinate Nix installation.\n\n### Focused maintenance and recovery\n\nUse `./install --scripts-only` to update only public commands in `~/.local/bin`; it never selects or activates a backend. Legacy mode on a Home Manager-managed macOS user is blocked unless `--allow-mixed-backends` explicitly acknowledges the recovery risk.\n\nLegacy-only options are `--skip-brew`, `--skip-packages`, and `--skip-links`. Nix-only options are `--configuration`, `--skip-npm`, and `--nix-distribution`. Incompatible option combinations fail instead of being ignored. Run `./install --help` for the complete interface.\n\n---\n\n## Configuration ownership and linking\n\nThe repository uses two complementary activation mechanisms:\n\n| Mechanism | Owns | Use it for |\n| --- | --- | --- |\n| Home Manager and nix-darwin | Paths explicitly declared in [`nix/home.nix`](nix/home.nix) and [`nix/darwin.nix`](nix/darwin.nix) | Reproducible user and system configuration |\n| Convention linker | Eligible files under [`home/`](home/), [`home-darwin/`](home-darwin/), and public executables directly under `bin/<domain>/` | Home files and commands not declared in Nix |\n\nThe linker maps home-tree files to their equivalent paths below `$HOME` and links public commands to `~/.local/bin`. It previews by default and refuses unmanaged collisions unless explicitly forced.\n\n```bash\n# Inspect planned links\nuv run bin/core/link-dotfiles.py --dry-run\n\n# Apply only after reviewing the plan\nuv run bin/core/link-dotfiles.py --apply --yes\n\n# Link only public commands\nuv run bin/core/link-dotfiles.py --commands-only --apply --yes\n```\n\n> [!WARNING]\n> Use `--force` only when you have confirmed that replacing an existing target is correct. Pruning removes only links recorded in the linker's ownership state.\n\n---\n\n## Everyday operations\n\n### Environment and packages\n\n```bash\n# Check or change the active shell profile\nwork-mode status\nwork-mode work\nwork-mode personal\n\n# Start a new shell after switching profiles\nexec zsh\n\n# Preview Nix operations\nnix-activate --dry-run\nnix-rebuild --dry-run\nnix-update --dry-run\n\n# Validate the Nix configuration\nnix-validate\n```\n\n### Credentials\n\n```bash\n# Prompt for an API key and store it in the macOS Keychain\nstore-api-key OPENAI_API_KEY\n\n# Retrieve a stored API key\nget-api-key OPENAI_API_KEY\n\n# Manage encrypted credential files\ncredfile ~/.secrets/example\ncredmatch example\n```\n\n> [!WARNING]\n> Never pass a secret as a command argument. Use the interactive prompt, standard input, or a file so it does not enter shell history or process listings.\n\n### Synchronization and shell maintenance\n\n```bash\n# Synchronize this dotfiles repository\nhome-sync status\nhome-sync sync\n\n# Maintain shell performance\nzsh-benchmark\nzsh-compile\nzsh-trim-history\n```\n\n---\n\n## Project map\n\n```text\n.\n├── install          # Nix dispatcher and legacy installer\n├── flake.nix        # Nix flake entry point\n├── nix/             # Host, Home Manager, package, and nix-darwin modules\n├── home/            # Common home-directory source files\n├── home-darwin/     # macOS-specific home-directory source files\n├── bin/             # Public tools grouped by domain\n│   ├── core/        # Nix, linker, shell, sync, and utility commands\n│   ├── credentials/ # Keychain and encrypted-credential tools\n│   ├── git/         # Git workflow helpers and hooks\n│   ├── ide/         # IDE integrations\n│   ├── macos/       # macOS-specific utilities\n│   └── test/        # Repository test runner\n├── packages/        # Package-manager configuration\n├── git/             # Git configuration and shared helpers\n├── zsh/             # Zsh configuration and support files\n├── tests/           # Bats, Python, and integration coverage\n└── docs/            # Architecture, guides, and operational documentation\n```\n\n---\n\n## Validate changes\n\nRun the checks appropriate to the surface you changed:\n\n```bash\n# Shell syntax\nbash -n install\n\n# Static and evaluated Nix checks\nnix-validate --static\nnix-validate\n\n# Confirm linking is safe before applying it\nuv run bin/core/link-dotfiles.py --dry-run\n\n# Integration tests\nbin/test/run-tests\n\n# Focused Python tests\npython3 tests/test_git_smart_merge.py\npython3 tests/test_uv_resolver.py\n\n# Full local macOS CI gate before opening or updating a pull request\nscripts/local-ci.sh\n```\n\n> [!NOTE]\n> `scripts/local-ci.sh` runs each macOS stage in an isolated temporary workspace. Use `--include-destructive` only when you explicitly want to test Nix installation in a disposable VM.\n\nSee [`tests/README.md`](tests/README.md) for Bats test prerequisites, filtering, timing, TAP output, and parallel execution.\n\n---\n\n## Documentation\n\n- [Architecture overview](docs/architecture.md)\n- [Convention linker source inventory](docs/linking-source-inventory.md)\n- [Credential management guide](docs/guides/CREDENTIAL_MANAGEMENT.md)\n- [Git virtual worktree guide](docs/git-virtual-worktree.md)\n- [Script quick reference](docs/scripts/quick-reference.md)\n",
  "bytes": 7649,
  "sha": "99199ac1f7efe0c94374230a71b698e02a5042739a3b44c8d6f9ee5aa1aa2859",
  "repo_slug": "brunogama/dotfiles",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_brunogama_dotfiles_okf_index_md_13858370/readme"
}