flake: document the github:-free update procedure

A plain `nix flake update` re-reads transitive inputs from their upstream
flakes, whose declarations still use the `github:` shorthand, so the
lock's locked entries for them would regress to the github fetcher and
403 behind the Claude web sandbox proxy.

Record the tested `--override-input` invocation that keeps every node on
the git fetcher, the check that catches inputs upstream flakes gain later
(exercised for real: agda.nix has grown a categorical-crypto input since
our pin), and the note that regressed *original* fields after an update
are harmless because consumers fetch by the *locked* entries.

Verified 2026-08-10 in a scratch copy: the documented command produces a
lock with zero github-locked nodes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: williamdemeo

flake.nix

@@ -8,6 +8,28 @@
   # git-over-https works there for any public repo. narHashes are identical
   # between the two fetchers, so the pins are unchanged. nixpkgs adds
   # `shallow=1` so a binary-cache miss fetches only the locked rev.
+  #
+  # UPDATING: a plain `nix flake update` re-reads TRANSITIVE inputs from their
+  # upstream flakes (still declared github:) and would regress the lock. Use:
+  #
+  #   nix flake update \
+  #     --override-input agda-nix/abstract-set-theory git+https://github.com/input-output-hk/agda-sets \
+  #     --override-input agda-nix/categorical-crypto git+https://github.com/input-output-hk/categorical-crypto \
+  #     --override-input agda-nix/flake-utils git+https://github.com/numtide/flake-utils \
+  #     --override-input agda-nix/flake-utils/systems git+https://github.com/nix-systems/default \
+  #     --override-input agda-nix/iog-prelude git+https://github.com/input-output-hk/iog-agda-prelude \
+  #     --override-input agda-nix/standard-library-classes git+https://github.com/agda/agda-stdlib-classes \
+  #     --override-input agda-nix/standard-library-meta git+https://github.com/agda/agda-stdlib-meta \
+  #     --override-input flake-parts/nixpkgs-lib git+https://github.com/nix-community/nixpkgs.lib
+  #
+  # then verify nothing github-locked slipped in (upstreams gain inputs over
+  # time; `nix flake metadata` shows a new input's path — append an override):
+  #
+  #   python3 -c "import json; L=json.load(open('flake.lock'))['nodes']; \
+  #     print(*[k for k,v in L.items() if v.get('locked',{}).get('type')=='github'] or ['OK'])"
+  #
+  # (Transitive *original* fields read github after an update; harmless —
+  # fetches go by the *locked* entries.)
   inputs = {
     nixpkgs.url = "git+https://github.com/NixOs/nixpkgs?shallow=1";