docs: add captain-approved VISION.md

[kunchenguid]

Summary

• Add the first VISION.md: an acceptance policy for gnhf's future, drafted from the repo's real merged-PR history (55 merged PRs by @kunchenguid, plus refusal signals such as the Swival adapter closure in feat(agents): add support for the Swival coding agent #109) and approved by the author on an interactive review board ("ship it").
• Point AGENTS.md at VISION.md as the owner of feature/scope acceptance decisions.

Process

The draft was built with the /vision skill: evidence mining from merged PRs and closed refusals, a from-scratch draft where every line traces to named PRs, then 12 steelmanned fault-line hypotheticals answered by the author on a lavish review board. All verdicts were folded in with traced edits before approval.

Author verdicts (durable calibration record)

Text annotations:

• "Never wake up empty-handed" heading -> renamed "No work is ever lost" (heading now matches the section's content).
• "Fun is part of the contract" -> renamed "Delight is part of the contract".

Hypotheticals:

• H-1 Retire the native adapters: Conditional - "only if the ACP variant doesn't lose key functionality compared to the native one"
• H-2 The morning half (gnhf review TUI): In vision - "it serves the mission better"
• H-3 Fleet mode: Off mission - "this can be done with running multiple gnhf instances. the extra machinery is not necessary"
• H-4 Open the PR while I sleep (--open-pr): Off mission - "this can be done in another layer of automation. it's not the core value prop of gnhf"
• H-5 Trust but verify (verify command): Off mission - "these can be configured as agent hooks. gnhf should not own it"
• H-6 Eyes on the failure classes (opt-in per-iteration diagnostics): In vision - "this seems purely a debuggability improvement with no product implications"
• H-7 Batteries-included objectives: Off mission - "each repo is different. it's hard to come up with one-size-fits-all objectives that enough users would find helpful"
• H-8 Survive the closed lid (--daemon): In vision - "this helps serve the mission better"
• H-9 Drop Windows: Off mission - "we want to serve as many users as possible, which means we should try to cover more OS not less"
• H-10 Homebrew and Nix ([FEATURE 🥀] There is not Nix Or Homebrew Install #196): In vision - "supporting more users with the same product is almost always desired"
• H-11 Whisper to the loop (mid-run steering): In vision - "this helps the user gain more control"
• H-12 Signed commits: Conditional - "only if we can figure out an unattended way to do this."

Distilled: the bedtime-to-morning run lifecycle belongs to gnhf (survive the night, steer, review); gnhf does not own what another layer already owns (outer automation, agent hooks, multiple instances, the user's own prompts); reach beats maintenance thrift; ACP-first with capability parity gating adapter removal; telemetry's invariant is anonymity, not event count; anything that can hang an unattended run is refused until it works unattended.

This section is the durable answers record recommended by the /vision skill - worth keeping next to the vision (here in the PR, or copied into the repo if preferred).

🤖 Generated with Claude Code

[kushvinth]

Brother Nix/Brew install docs Please