nixos-clanker-vm/AGENTS.md

# AGENTS.md

Context for AI coding agents (opencode) working in this repository.

## What this is

Declarative [Nix](https://nixos.org) + [Home Manager](https://github.com/nix-community/home-manager)
configuration for `debian-13-opencode`, a **Debian 13 (trixie) non-NixOS VM**
running **standalone Nix**. This repo is the single source of truth for the
user's shell, tools, and dotfiles. System-wide Nix settings are applied
separately by `install.sh`.

There is no NixOS module system here — Home Manager is used in standalone mode.

## Environment

- OS: Debian GNU/Linux 13 (trixie), `x86_64-linux`, kernel 6.12.
- Nix 2.26.3 with `nix-command` + `flakes` (declared in `config/nix.conf`).
- Home Manager `26.11-pre`; `home.stateVersion = "26.05"`.
- User `user`, home directory `/home/user`.
- Login shell is bash, which immediately `exec fish` for interactive sessions.
- Managed packages: `opencode`, `ncdu`, `nano`, `tinfoil-proxy`.
- Managed programs: bash, fish, tmux, starship, home-manager.
- **No linter, formatter, CI, or git hooks are configured.** Do not assume
  `nixfmt`, `alejandra`, `statix`, `deadnix`, `shellcheck`, or `treefmt` exist.
- Working tree is expected to report `warning: Git tree '...' is dirty`; this
  is normal and does not affect evaluation.

## Layout

| Path                        | Purpose                                                            |
| --------------------------- | ------------------------------------------------------------------ |
| `flake.nix`                 | Root flake: overlay for `tinfoil-proxy`, `homeConfigurations.user`. |
| `home/default.nix`          | Home Manager config: packages, file links, programs, user service.  |
| `config/nix.conf`           | Source of truth for Nix settings (`sandbox`, flakes).               |
| `config/starship.toml`      | Starship "nerd-font-symbols" preset.                                |
| `config/opencode.jsonc`     | Global opencode config, incl. the `tinfoil` provider.               |
| `tinfoil-proxy/flake.nix`   | Self-contained flake exposing the `tinfoil-proxy` package.          |
| `tinfoil-proxy/package.nix` | Derivation: version, hashes, `buildGoModule` with `go_1_27`.        |
| `install.sh`                | Installs `config/nix.conf` to `/etc/nix/nix.conf` (sudo, backs up). |
| `flake.lock`                | Pinned inputs; **intentionally tracked** for reproducibility.       |

## Commands

```sh
home-manager switch --flake .#user      # apply the user config (the main loop)
sudo ./install.sh                       # install /etc/nix/nix.conf (idempotent)
nix build ./tinfoil-proxy               # build only the Go proxy package
nix flake show                          # list flake outputs
nix flake update                        # bump pinned inputs
nix flake update && home-manager switch --flake .#user   # update + apply
```

Inspect without building:

```sh
nix eval .#packages.x86_64-linux.default.pname
```

### Inputs (currently pinned)

- `nixpkgs` — `nixpkgs-unstable`, rev `39ad350a…`.
- `home-manager` — rev `dfadbe5…`, follows this `nixpkgs`.
- `tinfoil-proxy` — `path:./tinfoil-proxy` (local sub-flake).

## How configuration is managed

Home Manager drives everything from `home/default.nix` via three mechanisms:

1. **Files linked from this repo** — `home.file.…source = ../config/<file>`.
   Editing a file in `config/` and re-applying updates the symlink target in
   `~/.config`. Currently linked: `starship.toml`, `nix/nix.conf`,
   `opencode/opencode.jsonc`.
2. **Program modules** — `programs.<name>`. Prefer these over raw dotfiles.
3. **Environment variables** — `home.sessionVariables`.

The `tinfoil-proxy` user service is declared at
`systemd.user.services.tinfoil-proxy` and starts at login/boot (linger is
enabled).

## Conventions

- **Declarative first.** Add tools to `home.packages`; link config via
  `home.file`; use `programs.<name>` rather than hand-editing files in `$HOME`.
- Use 2-space indentation in Nix, keep trailing newlines, and match the
  existing concise style. Do not add comments unless they add real value.
- When renaming/moving config, keep the `config/` filename, the `home.file`
  target path, and the README in sync.
- Keep `"$schema": "https://opencode.ai/config.json"` at the top of
  `config/opencode.jsonc`.
- Username and system are hardcoded in **both** `flake.nix` and
  `tinfoil-proxy/flake.nix`; keep them consistent when either changes.

## Guardrails

- **Do not run `home-manager switch`, `sudo ./install.sh`, or `git commit`
  unless explicitly asked.** Propose the command instead.
- Never commit secrets. `TINFOIL_API_KEY` is injected via `{env:...}`; keep it
  out of the repo and the Nix store.
- Do not remove `flake.lock` from tracking or add build outputs (`result*`) to
  git (already ignored by `.gitignore`).
- Do not introduce a formatter/linter/CI unless asked.

## Gotchas

- `packages.default` in the root flake **is** `tinfoil-proxy`, not the config.
- An overlay injects `tinfoil-proxy` into `pkgs`, which is how
  `home/default.nix` refers to `pkgs.tinfoil-proxy`.
- Interactive bash `exec fish`, so fish (not bash) reads most interactive
  config; `home.sessionVariables` exports `NIX_SHELL_PRESERVE_PROMPT=true`.
- `install.sh` only compares/installs `config/nix.conf`; it backs up any
  differing `/etc/nix/nix.conf` to `/etc/nix/nix.conf.bak.<timestamp>`.

## OpenCode

- `config/opencode.jsonc` declares the `tinfoil` provider via
  `@ai-sdk/openai-compatible`, pointing at the local proxy
  `http://127.0.0.1:3301/v1`, with `apiKey: {env:TINFOIL_API_KEY}`.
- Model IDs and context/output limits are listed under `provider.tinfoil.models`.
  Update that block to change available models.
- `~/.config/opencode/package.json`, `package-lock.json`, and `node_modules/`
  are **local and unmanaged** (gitignored) — Home Manager only owns
  `opencode.jsonc`.
- opencode reads config once at startup; **restart opencode** after changing
  any config, agent, or skill file.
- This `AGENTS.md` is auto-loaded as project context.

## Git

- Default branch: `main`. No remote is configured.
- Commit style: short, imperative, capitalized subject (e.g.
  `Adopt Home Manager; manage starship, nix.conf, and opencode config`).
- Only commit when explicitly asked.

## Reference

`README.md` is the user-facing guide (setup, customization, maintenance). Keep
it accurate when changing structure or commands.