local-dev skill: document gateway-isolation gotcha and fdev --port pitfall

[iduartgomez]

Summary

The local-dev skill (skills/local-dev/SKILL.md) describes how to run isolated local Freenet test nodes, but two gotchas that bit me during freenet-email E2E debugging are not covered. Both can silently invalidate "I'm testing locally" assumptions.

Gotcha 1: --data-dir doesn't isolate gateway bootstrap list

Currently the skill recommends:

freenet network --network-port 31338 --ws-api-port 7510 \
  --is-gateway --skip-load-from-network \
  --data-dir ~/freenet-test-node/data \
  --public-network-address 127.0.0.1 \
  --log-dir \"\$LOG_DIR\" --log-level debug

with the claim "Each node is fully isolated".

This is not true if the machine has a default freenet install — the bootstrap gateway list is read from ~/Library/Application Support/The-Freenet-Project-Inc.Freenet/gateways.toml (macOS) regardless of --data-dir. A peer started this way will dial public Freenet gateways (nova.locut.us, vega.locut.us by default) and try NAT traversal to real Freenet peers.

Fix to document: override HOME with a sandbox dir holding an empty gateways file:

mkdir -p ~/iso-home/Library/Application\ Support/The-Freenet-Project-Inc.Freenet
printf 'gateways = []\n' > ~/iso-home/Library/Application\ Support/The-Freenet-Project-Inc.Freenet/gateways.toml
HOME=~/iso-home freenet network --gateway \"127.0.0.1:31338,\$PUBKEY\" ...

(empty file trips `missing field 'gateways'` TOML error — must be `gateways = []`)

Verification step to add: tail peer log for `Starting initial join procedure with N gateways` — N must equal the number of `--gateway` flags. If higher, isolation is broken.

Upstream tracking: freenet/freenet-core#3980.

Gotcha 2: fdev defaults to port 7509

The skill mentions `fdev --port 7510` once but doesn't flag the default (7509) or the failure mode. On a dev machine running the launchd-managed system freenet service (which owns 7509), `fdev publish ...` without `--port` silently goes to that node, not the isolated test node.

Symptom: "Signature verification failed: signature error" on a fresh test publish, because the system node has stale published-contract state from a previous run signed by a different key.

Fix to document: add a callout box stating "Always pass `--port` to fdev when targeting a non-default test node. Without it, fdev publishes to whichever node owns 7509 — which on most dev machines is the launchd-managed system service, not your test node."

Why it matters

Both gotchas produce silent / misleading symptoms — peer joins public network without warning, publish hits wrong node and surfaces as a sigverify error. Documenting them in the skill saves the next person ~30 min of head-scratching per gotcha.

Suggested patch sketch

Add a new "Isolation pitfalls" subsection to the local-dev skill:

## Isolation pitfalls

### --data-dir doesn't isolate gateway list

freenet reads the global gateways.toml at \`~/Library/Application Support/...\` (macOS) or \`~/.config/freenet/...\` (Linux) regardless of \`--data-dir\`. To fully isolate, override HOME:

\`\`\`bash
mkdir -p ~/iso-home/Library/Application\\ Support/The-Freenet-Project-Inc.Freenet
printf 'gateways = []\\n' > ~/iso-home/Library/Application\\ Support/The-Freenet-Project-Inc.Freenet/gateways.toml
HOME=~/iso-home freenet network --gateway \"127.0.0.1:31338,\$PUBKEY\" ...
\`\`\`

Verify with: \`grep \"Starting initial join procedure\" \"\$LOG_DIR\"/freenet.*.log\` — gateway count must match \`--gateway\` flag count.

Tracking upstream: freenet/freenet-core#3980

### fdev defaults to 7509

\`\`\`bash
# WRONG: silently targets whichever node owns 7509 (often the system service)
fdev publish --code ... contract ...

# RIGHT
fdev --port 7510 publish --code ... contract ...
\`\`\`

If you see \"Signature verification failed\" on a fresh publish, you probably published to the wrong node.

Context

Filed from a freenet-email debugging session. Both gotchas cost real time (~30 min each) before identification.