feat(streaming): Make streaming primary, add body_or_error, rename NOTE_NO_BUFFERED

Resolves ISSUE-env-get-streaming-and-overflow-error.md by making the streaming response path the recommended default and turning the silent failure modes around tree-mode access into actionable, discoverable errors.

env.get docs + overflow message (the original issue)

- Overlay adds prose to env.get's Doxygen comment calling out that the
response is unbounded when no `name` is given, and recommending the streaming .into(JsonSink&) overload (with set_response_buffer() as the fallback when a bounded staging buffer is acceptable).
- spec_parser.py now combines OpenAPI `summary` + `description` so the
overlay can extend prose without overwriting upstream summaries.
- generate.py's markdown stripper now ignores `_` boundaries inside
word characters, preserving snake_case identifiers in `code spans` that the old regex was destroying (`set_response_buffer` → `setresponsebuffer`, `_temp.qo` → `temp.qo`, `ALT_DFU` → `ALTDFU`, `ver_major` → `vermajor`, etc.). Cascades through several api/*.hpp.
- The response-overflow error at protocol.hpp/transact.hpp now names
both escape hatches: `set_response_buffer()` and `.into(JsonSink&)`. Zero AVR flash cost (NOTE_SHORT_ERRORS collapses the literal to "E"). New test in test_buffered_bridge.cpp pins the contract.

Loud failure on body() in streaming mode

- New `Response::body_or_error()` returns an explicit
Result<const JsonReader*> with Error::NotReady + actionable message when the response was populated by the streaming SAX path. Old body() stays for back-compat (now [[nodiscard]]).
- `Response::was_streaming_parse()` exposes the flag for callers that
want to branch on mode at runtime.
- streaming_parse_used_ flag is set by Sink::reset and lives next to
the two unique_ptrs in the buffered section of Response.
- New test in test_body.cpp covers both modes.

NOTE_NO_BUFFERED → NOTE_NO_JSON_TREE

- Canonical macro renamed to match the user-facing vocabulary
(streaming vs tree, not streaming vs buffered).
- NOTE_NO_BUFFERED is honoured as a deprecated alias via a back-compat
shim in note_config.hpp — existing user build_flags keep working.
- Compile-check tests use the new name; one new compile-check
(note_no_buffered_alias.cpp) pins the back-compat shim.

Streaming as the primary path

- New `Notecard(ITransact&, Allocator = {})` convenience ctor
eliminates the nullptr-backend boilerplate when wiring streaming with a non-Protocol transport.
- docs/getting-started.md leads with the streaming pattern; tree mode
is shown as the opt-in when body() or the lambda request builder is needed.
- docs/streaming-and-tree.md documents body_or_error(), the per-
Response RAM savings of setting NOTE_NO_JSON_TREE=1 (24 bytes on 64-bit hosts, ~12 bytes on 32-bit embedded), and the rationale for not pursuing per-instance compile-time gating (covered by the macro flag + the runtime check).
- docs/feature-flags.md + docs/environment-variables.md updated.

Author: m-mcgowan

docs/environment-variables.md

@@ -178,7 +178,7 @@ if (rsp) {
 }
 ```
 
-On AVR-class builds (`NOTE_MINIMAL` sets `NOTE_NO_BUFFERED=1`), tree mode is compiled out — the `transact` + `scan` pattern above is the only option for dynamic keys.
+On AVR-class builds (`NOTE_MINIMAL` sets `NOTE_NO_JSON_TREE=1`), tree mode is compiled out — the `transact` + `scan` pattern above is the only option for dynamic keys.
 
 ## C++ level
 

docs/feature-flags.md

@@ -44,7 +44,7 @@ build_flags = -DNOTE_MINIMAL -UNDEF_NOTE_NO_CRC
 | Flag | Default | Minimal | Effect | Savings |
 |------|---------|---------|--------|---------|
 | `NOTE_JSONB` | `0` | **(M)** `1` | Use [JSONB binary wire format](jsonb.md) instead of JSON text. Requests/responses encoded as COBS-framed binary opcodes. CRC is bypassed (COBS provides framing but not integrity — CRC handles that separately). Raw JSON string bodies are a compile error — use lambdas or typed structs. Requires Notecard firmware 11.x+. | ~1.9 KB flash (replaces JSON builder/lexer with the smaller JSONB builder/parser) |
-| `NOTE_NO_BUFFERED` | off | **(M)** on | Disable `JsonBackend`/`JsonReader` tree parse path. Only streaming SAX parse available. (Macro name retained for backwards compatibility.) | ~2-4 KB flash, ~300 B RAM |
+| `NOTE_NO_JSON_TREE` | off | **(M)** on | Disable `JsonBackend`/`JsonReader` tree-mode parse path (`.body()`, `.body_or_error()`, `parse(reader)`). Only streaming SAX parse available. The legacy spelling `NOTE_NO_BUFFERED` is honoured as a deprecated alias. | ~2-4 KB flash, ~300 B RAM |
 | `NOTE_NO_CRC` | off | **(M)** on | Disable CRC32 on request/response framing. (CRC not supported by JSONB on Notecard)| ~200 B flash, 64 B .data (LUT) |
 | `NOTE_NO_MD5` | off | **(M)** on | Disable MD5 for binary transfer verification. | ~512 B .data (tables) |
 | `NOTE_NO_STD_STRING` | off | **(M)** on | Disable `std::string`-dependent features (debug wire tracing, some transport methods). Required for AVR (no `<string>` header). | Enables AVR builds |

docs/getting-started.md

@@ -48,24 +48,24 @@ A minimal `main.cpp` — replace `MySerialHal` with whatever talks to your hardw
 ```cpp
 #include <note/notecard.hpp>
 #include <note/api.hpp>
-#include <note/backends/cjson.hpp>
 #include <note/link/serial.hpp>
 #include <note/protocol.hpp>
 
 int main() {
     MySerialHal hal;                                 // your serial HAL impl
     note::link::SerialFramer serial_hal(hal);        // note::Hal — wire framing
     note::Protocol transport(serial_hal);            // ITransact — wire protocol
-    note::backends::CjsonBackend backend;            // tree-mode JSON backend
 
-    note::Notecard nc(backend, transport);
+    note::Notecard nc(transport);                    // streaming — no JSON backend needed
     note::Api api(nc);
 
     auto r = api.card.version().execute();
     if (r) std::printf("Notecard %.*s\n", (int)r.version.size(), r.version.data());
 }
 ```
 
+Streaming is the recommended default — typed response fields, struct body parsing via `.into(struct)`, and the rest of the API surface work without a JSON tree-mode backend linked, and the wire response can be arbitrarily large. Switch to tree mode (`Notecard nc(backend, transport);` with a `note::backends::CjsonBackend backend;`) only when you need `response.body()` for ad-hoc field walks or the `nc.request("endpoint", [&](auto& b){ … })` lambda builder — see [`docs/streaming-and-tree.md`](streaming-and-tree.md) for the full tradeoff.
+
 Build: `cmake -S . -B build && cmake --build build`. The runnable companion to this section is [`examples/stdcpp/getting-started.cpp`](../examples/stdcpp/getting-started.cpp), which uses a mock transport so you can experiment without hardware. See [`examples/stdcpp/README.md`](../examples/stdcpp/README.md) for the full example index.
 
 ### ESP-IDF
@@ -76,7 +76,7 @@ The HAL implementation for ESP-IDF UART/I2C drivers is yours to wire (the same `
 
 ## Your first request
 
-> Throughout the rest of this page, `nc` is the API surface. On Arduino, that's the `Notecard nc;` you declared. On stdcpp/ESP-IDF, after `Notecard nc(backend, transport); Api api(nc);` you write `api.card.version()` instead — the calls are identical, the receiver isn't. See [using-the-api.md](using-the-api.md) for the full picture.
+> Throughout the rest of this page, `nc` is the API surface. On Arduino, that's the `Notecard nc;` you declared. On stdcpp/ESP-IDF, after `Notecard nc(transport); Api api(nc);` you write `api.card.version()` instead — the calls are identical, the receiver isn't. See [using-the-api.md](using-the-api.md) for the full picture.
 
 Walking through one full request — `card.version`, the simplest readable Notecard endpoint — top to bottom:
 

docs/streaming-and-tree.md

@@ -42,7 +42,21 @@ if (r && r.body()) {
 }
 ```
 
-In streaming mode the response bytes are gone once the SAX parser has run, so `r.body()` returns null. The same use case is served by committing the body shape ahead of time, either with a struct via `.into(struct)` or with a SAX `JsonSink` for fully ad-hoc parsing:
+In streaming mode the response bytes are gone once the SAX parser has run, so `r.body()` returns null. Because a null return is also the legitimate "response carried no body field" result in tree mode, the two cases look identical to the caller — for mixed builds where the same code path may run in either mode, prefer `r.body_or_error()`, which returns an explicit `Error::NotReady` when the Notecard was in streaming mode:
+
+```cpp
+auto r = nc.note.get("data.qi").execute();
+if (r) {
+    auto safe = r.body_or_error();
+    if (safe.has_value()) {
+        // *safe is a const JsonReader*, may still be null if no body field
+    } else {
+        // safe.error().code == Error::NotReady — running in streaming mode
+    }
+}
+```
+
+The same use case is served by committing the body shape ahead of time, either with a struct via `.into(struct)` or with a SAX `JsonSink` for fully ad-hoc parsing:
 
 ```cpp
 struct Readings {
@@ -112,11 +126,24 @@ This table summarizes the surfaces touched by the mode choice. Every other surfa
 | Binary transfers (COBS) | yes | yes |
 | Error handling (`ApiResult`) | yes | yes |
 | Lambda request builder (`nc.request(...)`) | yes | — |
-| `response.body() -> JsonReader*` | yes | — |
+| `response.body() -> JsonReader*` | yes | — (null) |
+| `response.body_or_error()` | success | `Err::NotReady` |
 | Requires `JsonBackend` | yes | no |
 | Zero-heap capable | depends on backend | yes |
 
-Defining `NOTE_NO_BUFFERED` removes tree mode entirely (a saving of roughly 2 to 4 KB of flash). `NOTE_MINIMAL` sets this automatically.
+Defining `NOTE_NO_JSON_TREE` removes tree mode entirely (a saving of roughly 2 to 4 KB of flash). `NOTE_MINIMAL` sets this automatically. The legacy name `NOTE_NO_BUFFERED` is honoured as an alias for backward compatibility; new code should use `NOTE_NO_JSON_TREE`.
+
+`NOTE_NO_JSON_TREE` also drops two `std::unique_ptr<JsonReader>` fields and a discriminator bool from every `Response` struct — measured at **24 bytes per response** on 64-bit hosts (and ~12 bytes on 32-bit embedded targets) even for code that never calls `body()`. The header-only `body()` / `body_or_error()` / `parse(reader)` methods themselves are DCE'd by the linker when unreferenced, so the flash cost of leaving the flag off is near zero — the per-response RAM is the real penalty. Streaming-only projects on memory-constrained MCUs should set `NOTE_NO_JSON_TREE=1` for the RAM win even if their code already happens to be streaming-clean.
+
+## Why there is no per-instance compile-time gate
+
+`response.body()` exists when the build allows tree mode. There is no separate `StreamingResponse` type that omits `body()` at compile time when *this particular Notecard instance* uses streaming. That sounds like a useful safety net, and it was considered, but it doesn't pay off:
+
+- The shape needed — `Notecard<note::Streaming>` vs `Notecard<note::JsonTree>` with mode-aware `Response` traits — would require templating `Notecard`, `StaticNotecard`, and the `Api` wrapper on a mode tag, and threading that tag through every generated endpoint. Existing `Notecard nc;` syntax would need a migration shim.
+- It only catches one case: mixed builds where the user wrote streaming-only code but left `NOTE_NO_JSON_TREE` off. That case is already caught at runtime by `body_or_error()` — explicit `Error::NotReady` with an actionable message — and `was_streaming_parse()` is available for introspection. Whole-program elimination is covered by the macro flag.
+- For users who only ever use streaming, setting `NOTE_NO_JSON_TREE=1` removes `body()` from the compiled API surface entirely. That's the same compile-time safety the template approach would deliver, without the architectural surface.
+
+So the safety story is: **(1)** macro flag for whole-program compile-time removal; **(2)** `body_or_error()` + `was_streaming_parse()` for runtime detection in mixed builds; **(3)** `[[nodiscard]]` on `body()` so the compiler nags about unused returns. Per-instance compile-time gating isn't planned.
 
 ## See also
 

notecard-api.openapi.overlay.json

@@ -122,6 +122,11 @@
                     }
                 }
             }
+        },
+        "/env/get": {
+            "get": {
+                "description": "When called without a `name` (or `names`), `env.get` returns the full environment-variable set known to the Notecard. The response size scales with the Notehub project and may exceed the default response buffer, surfacing as `Error::Overflow`. For this shape, prefer the streaming `.into(JsonSink&)` overload — body events stream off the wire and the env set can be arbitrarily large. As an alternative, `Notecard::set_response_buffer()` can enlarge the staging buffer if a bounded response is acceptable."
+            }
         }
     }
 }

src/note/api.hpp

@@ -2340,6 +2340,15 @@ class Api {
 
         /// Returns a single environment variable, or all variables according to
         /// precedence rules.
+        ///
+        /// When called without a `name` (or `names`), `env.get` returns the
+        /// full environment-variable set known to the Notecard. The response
+        /// size scales with the Notehub project and may exceed the default
+        /// response buffer, surfacing as `Error::Overflow`. For this shape,
+        /// prefer the streaming `.into(JsonSink&)` overload — body events
+        /// stream off the wire and the env set can be arbitrarily large. As an
+        /// alternative, `Notecard::set_response_buffer()` can enlarge the
+        /// staging buffer if a bounded response is acceptable.
         auto get() { return create_<api::EnvGet>(); }
 
         /// Get the time of the update to any environment variable managed by
@@ -2665,20 +2674,20 @@ class Api {
 
 #if __cplusplus >= 202002L
         /// Add a "device health" log message to send to Notehub on the next
-        /// sync via the healthhost.qo Notefile.
+        /// sync via the _health_host.qo Notefile.
         template<typename T_ = TargetT_>
         requires (target_supports<T_, api::HubLog>())
         auto log() { return create_<api::HubLog>(); }
 
         /// Add a "device health" log message to send to Notehub on the next
-        /// sync via the healthhost.qo Notefile.
+        /// sync via the _health_host.qo Notefile.
         template<typename T_ = TargetT_>
         requires (!target_supports<T_, api::HubLog>() && !T_::strict)
         [[deprecated("hub.log is not available on this target")]]
         auto log() { return create_<api::HubLog>(); }
 #else
         /// Add a "device health" log message to send to Notehub on the next
-        /// sync via the healthhost.qo Notefile.
+        /// sync via the _health_host.qo Notefile.
         auto log() { return create_<api::HubLog>(); }
 #endif
 

src/note/api/card_attn.hpp

@@ -390,7 +390,7 @@ struct CardAttn {
 
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
-#if !NOTE_NO_BUFFERED
+#if !NOTE_NO_JSON_TREE
             static Response parse(std::unique_ptr<JsonReader> reader_) {
                 Response rsp;
                 { note::string_view arr_[8]; auto n_ = reader_->get_string_array("files", arr_, 8); for (size_t i_ = 0; i_ < n_; ++i_) rsp.files.add(arr_[i_]); }
@@ -422,7 +422,7 @@ struct CardAttn {
                 return rsp;
             }
 #pragma GCC diagnostic pop
-#endif // !NOTE_NO_BUFFERED
+#endif // !NOTE_NO_JSON_TREE
 
             // SAX sink — zero-allocation streaming parse into Response fields.
             // String fields are interned into the StringPool immediately, so
@@ -512,7 +512,7 @@ struct CardAttn {
             }
 #endif
 
-#if !NOTE_NO_BUFFERED
+#if !NOTE_NO_JSON_TREE
         private:
             std::unique_ptr<JsonReader> reader_;
 #endif
@@ -831,7 +831,7 @@ struct CardAttn {
             /// field will not be present when the attention pin is `LOW`.
             note::ResponseField<bool> set{};
 
-#if !NOTE_NO_BUFFERED
+#if !NOTE_NO_JSON_TREE
             static Response parse(std::unique_ptr<JsonReader> reader_) {
                 Response rsp;
                 if (reader_->has("set")) rsp.set = reader_->get_bool("set");
@@ -847,7 +847,7 @@ struct CardAttn {
                 if (reader_.has("set")) rsp.set = reader_.get_bool("set");
                 return rsp;
             }
-#endif // !NOTE_NO_BUFFERED
+#endif // !NOTE_NO_JSON_TREE
 
             // SAX sink — zero-allocation streaming parse into Response fields.
             // String fields are interned into the StringPool immediately, so
@@ -880,7 +880,7 @@ struct CardAttn {
             }
 #endif
 
-#if !NOTE_NO_BUFFERED
+#if !NOTE_NO_JSON_TREE
         private:
             std::unique_ptr<JsonReader> reader_;
 #endif
@@ -1183,7 +1183,7 @@ struct CardAttn {
             /// field will not be present when the attention pin is `LOW`.
             note::ResponseField<bool> set{};
 
-#if !NOTE_NO_BUFFERED
+#if !NOTE_NO_JSON_TREE
             static Response parse(std::unique_ptr<JsonReader> reader_) {
                 Response rsp;
                 if (reader_->has("set")) rsp.set = reader_->get_bool("set");
@@ -1199,7 +1199,7 @@ struct CardAttn {
                 if (reader_.has("set")) rsp.set = reader_.get_bool("set");
                 return rsp;
             }
-#endif // !NOTE_NO_BUFFERED
+#endif // !NOTE_NO_JSON_TREE
 
             // SAX sink — zero-allocation streaming parse into Response fields.
             // String fields are interned into the StringPool immediately, so
@@ -1232,7 +1232,7 @@ struct CardAttn {
             }
 #endif
 
-#if !NOTE_NO_BUFFERED
+#if !NOTE_NO_JSON_TREE
         private:
             std::unique_ptr<JsonReader> reader_;
 #endif
@@ -1661,7 +1661,7 @@ struct CardAttn {
             /// time) that the payload was stored by the Notecard.
             note::ResponseField<note::json_int_t> time{};
 
-#if !NOTE_NO_BUFFERED
+#if !NOTE_NO_JSON_TREE
             static Response parse(std::unique_ptr<JsonReader> reader_) {
                 Response rsp;
                 if (reader_->has("payload")) rsp.payload = reader_->get_string("payload");
@@ -1679,7 +1679,7 @@ struct CardAttn {
                 if (reader_.has("time")) rsp.time = reader_.get_int("time");
                 return rsp;
             }
-#endif // !NOTE_NO_BUFFERED
+#endif // !NOTE_NO_JSON_TREE
 
             // SAX sink — zero-allocation streaming parse into Response fields.
             // String fields are interned into the StringPool immediately, so
@@ -1725,7 +1725,7 @@ struct CardAttn {
             }
 #endif
 
-#if !NOTE_NO_BUFFERED
+#if !NOTE_NO_JSON_TREE
         private:
             std::unique_ptr<JsonReader> reader_;
 #endif
@@ -2211,7 +2211,7 @@ struct CardAttn {
 
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
-#if !NOTE_NO_BUFFERED
+#if !NOTE_NO_JSON_TREE
             static Response parse(std::unique_ptr<JsonReader> reader_) {
                 Response rsp;
                 { note::string_view arr_[8]; auto n_ = reader_->get_string_array("files", arr_, 8); for (size_t i_ = 0; i_ < n_; ++i_) rsp.files.add(arr_[i_]); }
@@ -2239,7 +2239,7 @@ struct CardAttn {
                 return rsp;
             }
 #pragma GCC diagnostic pop
-#endif // !NOTE_NO_BUFFERED
+#endif // !NOTE_NO_JSON_TREE
 
             // SAX sink — zero-allocation streaming parse into Response fields.
             // String fields are interned into the StringPool immediately, so
@@ -2314,7 +2314,7 @@ struct CardAttn {
             }
 #endif
 
-#if !NOTE_NO_BUFFERED
+#if !NOTE_NO_JSON_TREE
         private:
             std::unique_ptr<JsonReader> reader_;
 #endif

src/note/api/card_aux.hpp

@@ -493,7 +493,7 @@ struct CardAux {
 
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
-#if !NOTE_NO_BUFFERED
+#if !NOTE_NO_JSON_TREE
         static Response parse(std::unique_ptr<JsonReader> reader_) {
             Response rsp;
             if (reader_->has("mode")) rsp.mode = reader_->get_string("mode");
@@ -523,7 +523,7 @@ struct CardAux {
             return rsp;
         }
 #pragma GCC diagnostic pop
-#endif // !NOTE_NO_BUFFERED
+#endif // !NOTE_NO_JSON_TREE
 
         // SAX sink — zero-allocation streaming parse into Response fields.
         // String fields are interned into the StringPool immediately, so
@@ -592,7 +592,7 @@ struct CardAux {
         }
 #endif
 
-#if !NOTE_NO_BUFFERED
+#if !NOTE_NO_JSON_TREE
     private:
         std::unique_ptr<JsonReader> reader_;
 #endif