# Repo Gotchas

> Use before trusting CONTRIBUTING.md/Makefile/pre-commit claims literally, or when something documented doesn't behave as expected — "why doesn't X work", "is this hook actually active", "make help is missing stuff". Documents known drift between this repo's docs and its actual behavior.

- Skill: `aminedjeghri/repo-gotchas` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aminedjeghri/repo-gotchas`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aminedjeghri/repo-gotchas/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aminedjeghri (https://skillmd.com/u/aminedjeghri)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aminedjeghri/repo-gotchas

---


# Known drift between docs and reality in personal-os-setup

Cross-check these before assuming documentation is current — several claims in `CONTRIBUTING.md`/`Makefile` don't match the code as of this writing.

## Makefile

- **`make help`'s "Development:" section is broken**: it greps `makefiles/dev.mk`, which doesn't exist — the real file is `makefiles/check_format.mk`. Running `make help` prints a `grep: ... No such file or directory` and shows an empty Development section, even though `make lint`/`make format`/`make pre-commit`/`make pre-commit-install` all work fine when invoked directly.
- **`make test-installation`** (`uv run --directory . hello`) looks stale/broken — no `hello` console-script is registered in `pyproject.toml`'s `[project.scripts]` (only `personal-os-setup` is). Don't rely on it.
- **`make install` installs zero dev/docs dependencies** — `pyproject.toml` sets `default-groups = []`, so plain `uv sync` (what `make install` runs) gets you only runtime deps. Use `make install-dev` (`uv sync --all-groups`) to get pytest/ruff/pre-commit/mkdocs tooling.
- `common.mk`'s `$(UV)` variable falls back to `~/.local/bin/uv` if `uv` isn't on `PATH` — if it's installed somewhere else, every target fails with a plain "command not found" rather than a clear error.

## `.pre-commit-config.yaml` vs `CONTRIBUTING.md` § 3.1 "Security"

CONTRIBUTING.md claims `actionlint`, `zizmor`, and `pip-audit` are active local pre-commit security hooks. **They're commented out in `.pre-commit-config.yaml`** — not actually running. `bandit` and `markdown-link-check` are also present-but-commented-out. Nothing currently lints/security-scans the GitHub Actions workflow YAML itself — hand-review workflow diffs carefully, especially for script-injection via untrusted `${{ }}` interpolation, since no tool catches it here.

- `commitizen`'s hook only fires at git's `commit-msg` stage — `pre-commit run --all-files` (what `make pre-commit` runs) does **not** exercise it. A clean `make pre-commit` says nothing about whether your commit message is well-formed. See [[ship-feature]].
- `detect-secrets` runs **stateless** (no `--baseline` file configured) — false positives on new files must be suppressed with an inline `# pragma: allowlist secret` comment, not by adding the whole file to `--exclude-files` in `.pre-commit-config.yaml` (explicit repo convention).
- `end-of-file-fixer`/`trailing-whitespace`/`ruff --fix`/`ruff-format` all auto-rewrite files in place and fail the *first* run — re-`git add` and commit again, nothing is actually wrong.

## CONTRIBUTING.md references that don't exist

- `make docker-prod` / `make docker-dev` — **no such targets exist** in any `makefiles/*.mk`. There is no Docker-based dev workflow in this repo (only `make act`, which uses Docker to run GitHub Actions locally).
- "`make test` ... requires `.env` file" — not actually true; `common.mk` tolerates a missing `.env` (`-include .env`), and no unit test hard-requires one.
- "run `make pre-commit install`" (with a space) — the real target is `pre-commit-install` (hyphenated). As literally written this parses as two separate make targets (`pre-commit` and `install`), which happen to both exist, so it "works" by accident, not for the reason implied.

## `properdocs.yml` / docs site

See [[docs-site]] for the full `docs_dir: .` gotcha (any new top-level directory in the repo needs an entry in the `exclude` plugin's glob list, or it gets crawled into the published docs site).

## `packages.yaml`

No schema validation beyond one Python-level test asserting every `(distro, manager)` pair resolves to a real backend (`tests/unit/test_detect_os.py::TestPackagesYaml`). A malformed entry (wrong nesting, list where a dict is expected) surfaces as a `TypeError`/`AttributeError` at load time, not a clear validation error. See [[add-system-action]] for the required manager-registration step when adding a new manager name.

## Misc

- `src/awesome_os/` is dead — stale `__pycache__` from a prior package name, not live code (already flagged in `CLAUDE.md`, repeated here since it's easy to stumble on).
- `tests/archlinux/` is an orphaned Docker smoke-test harness, not wired into `make`/CI. See [[run-tests]].