Further changes

2026-10-09 00:07:16 +01:00
parent 555259e143
commit 5eb121d5e6
6 changed files with 1020 additions and 38 deletions
@@ -0,0 +1,138 @@
+# 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.