docs: expand Arduino firmware best practices, add debugging & connectivity docs

[Bucknalla]

Summary

Improves the Arduino documentation served by the firmware_best_practices and firmware_entrypoint MCP tools: restructures the entrypoint into a guided workflow, fixes several errors in the existing docs, expands best_practices.md, adds two new document types, and mines the note-arduino examples/API for additional patterns. All new content was grounded against the live Blues docs (docs_search / api_docs) — every Notecard request was API-verified before being documented.

Firmware entrypoint (index.md)

Reframed the entrypoint (served by firmware_entrypoint) from a reference page into an orientation document that sequences the build:

• Before You Start — a preflight checklist of requirements to gather from the user (ProductUID [REQUIRED], hardware/carrier, interface, sensors, sync cadence).
• Recommended Workflow — an ordered set of steps, each pointing at the relevant document_type, ending with power optimisation.
• Folded the previously duplicated standalone Power Management and Available Documentation sections into the workflow.
• Preserved the Code Layout, Design Patterns, and header-comment blocks.

Fixes to existing docs

• best_practices.md: corrected a printf-in-println() bug, replaced the nonexistent arduino_note_templates tool reference with firmware_best_practices + templates, and fixed a typo.
• index.md: fixed .c/.h → .cpp/.h, a typo, and corrected the Power Management section, which pointed at the wrong document_type.

Expanded best_practices.md

• Checking Notecard Responses — the responseError / deleteResponse / NULL-guard pattern, plus the sendRequestWithRetry / requestAndResponseWithRetry retry variants.
• General Embedded Firmware Best Practices — non-blocking millis() timing (overflow-safe), ISR discipline / volatile, bounded waits, fixed-width types, watchdog, state machines, and heap-fragmentation avoidance.

New document types

• debugging.md — setDebugOutputStream, logDebug/logDebugf, the debugSyncStatus() helper, card.trace mode, STLinkV3, AUX/FTDI and in-browser terminal monitoring, plus a debugging checklist.
• connectivity.md — hub.set mode/outbound/inbound tuning and persistence, forcing syncs (sync:true, hub.sync), status checks, polled inbound (note.get/note.changes), interrupt-driven inbound via the ATTN pin (card.attn), and offline resilience.

From the note-arduino repo

• Interrupt-driven inbound (card.attn) added to connectivity.md. Note: the note-arduino example arms ATTN with a reset mode that no longer exists in the current API — documented the verified arm,files / rearm form instead.
• debugSyncStatus() added to debugging.md for watching a sync live.
• Retry variants (sendRequestWithRetry / requestAndResponseWithRetry) documented in best_practices.md.
• Deliberately deferred: a binary-transfer topic (Examples 8/9) and Outboard DFU (Example 10), which need note-c header / hardware grounding before they're safe to document.

Discoverability

Since the handler reads docs/<sdk>/<type>.md, a new topic file is only reachable if something advertises it. Wired the new types into the entrypoint workflow in index.md and updated the document_type examples in tools.go and handlers.go.

Verification

• go build ./... passes.
• A throwaway test confirmed all six document_type files + index resolve through the handler's exact embed read path (removed after verifying).

🤖 Generated with Claude Code