docs: make the driver page a host reference, not a second authoring guide

[frahlg]

FTW and srcfl/device-drivers both carry a "how to write a driver" guide — 220 lines here, 268 upstream. They overlap on the entry points, the DRIVER block, the sign convention and the build-and-test loop, and nothing keeps them agreeing.

The upstream copy is built around blueprint/BLUEPRINT.lua and says outright that the blueprint is the specification, so it is the one a driver author reaches for. That makes the FTW copy the one that quietly goes stale — and #720 is moving the website's "Write a driver" link upstream right now, which removes the last reason anyone would open this one first.

The split

Divide by what each repository can actually answer.

Upstream owns authoring, and this page now links there in its first section: entry points, sign convention, what never to fabricate, the manifest/DRIVER version agreement, make test-driver, make check.

This page keeps what only FTW knows:

• what the host registers, as a table grouped by capability;
• how a capability is granted in YAML, and that an ungranted call fails before it reaches the network;
• when the host calls driver_default_mode — stale telemetry, reloads, removal, shutdown — which is a safety invariant of core, not a driver-authoring detail;
• identity and nameplate calls, and why set_make/set_sn matter (durable state is keyed by hardware identity, not the YAML name);
• where FTW resolves a driver file from: local → managed signed → bundled, the user-driver directories, and that the bundled tree is a pinned snapshot CI refuses to let you edit;
• how to test against a running instance, including that FTW does not watch Lua files.

220 → 159 lines.

Verification

• Every name in the host-API table was checked against host.RawSetString in go/internal/drivers/lua.go: 45 documented, 0 that do not exist. The only registered names not in the table are write and write_registers, the Blixt L1 aliases, which are covered in the prose below it rather than listed as canonical.
• http_patch and its capabilities.http.allow_write gate are included, from feat(drivers): host.http_patch write verb for device REST writes (#537) #716 earlier today.
• All relative links resolve; all four external links return 200.
• Nothing removed is lost: entry points, sign convention, manifest and make targets are upstream, and the drivers-beta promotion paragraph was already a duplicate of docs/device-repository.md, which this page links to.

Scope

README.md is deliberately untouched. #720 is editing the same Drivers section and has right of way; its "Start with docs/writing-a-driver.md" sentence still reads correctly, since this remains the right first page for the host side. Any README rewording belongs in a follow-up after #720 lands.

Documentation only, so the changeset gate exempts it.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4e3d4a5f93

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[miravoss26]

Turns docs/writing-a-driver.md from a second authoring guide into a host reference: sends authors upstream to srcfl/device-drivers for source, manifests and the authoring guide, and keeps this page for what the FTW host actually gives a driver (host API table, capability grants, sign convention, lifecycle).

• Docs-only, one file, CI green.
• The relocated authoring content (metadata/lifecycle/blueprint) now lives in device-drivers, which matches the "don't keep two guides that drift" intent. The host-side reference that stays is accurate against the old text it condenses: the http_patch double-gate (capabilities.http.allow_write on top of the plain http grant) plus its no-redirect rationale, driver_default_mode for stale telemetry, and the sign convention all read correctly.
• No security surface.

Good split and reads well. Safe to merge from my read.