chore: fix project conventions — .gitignore, CHANGELOG categories, docs naming

Assisted-by: MiMo V2.5 Pro

docs/decisions.md

@@ -0,0 +1,34 @@
+# Deferred decisions
+
+Design decisions deliberately postponed, with enough context to pick them up
+again without re-deriving the analysis.  Each entry records what is deferred,
+why, the options on the table, and the trigger that should reopen it.
+
+---
+
+## GOOBJ external (cross-package) symbol references
+
+**Status:** resolved (v0.29.0+, 2026-08-07).
+
+**Approach taken.**  Instead of parsing the compiler's iexport data (which
+would have required either `golang.org/x/tools` or an in-house parser), the
+resolver reads the **GOOBJ data directly** from the target package's `.a`
+archive.  The `.a` file contains a `_go_.o` member whose GOOBJ format is the
+same one gasm writes — the parser reuses the same layout (`blkSymdef`,
+`blkNonpkgdef`, the string table), so no new dependency was needed.
+
+**How it works.**
+
+1. `go list -json -export <pkg>` finds the target package's `.a` file.
+2. `extractGOOBJ` reads the ar archive, finds the `_go_.o` member, skips
+   the `"go object …\n!\n"` preamble and parses the GOOBJ header.
+3. `goobjFile.symbols()` walks `blkSymdef` and `blkNonpkgdef` in definition
+   order — the same order the linker uses — to build the symbol → index
+   mapping.
+4. `resolveExternalSymbols` wires the resolved `{PkgIdx, SymIdx}` into the
+   GOOBJ emission.
+
+The resolver is invoked automatically when `img.Externals` is non-empty; it
+runs `go list` as a subprocess (consistent with `toolchainObjectPreamble`
+which already calls `go tool asm`).  All symbol data is cached per package
+for the lifetime of the GOOBJ emission.