Collection Toolbar — segment slot + standard collection segment

koder-app specs/koder-app/collection-toolbar.kmd

Padrão de framework da Koder Stack para coleta de dados in-app, em TODAS as variantes de UI de TODOS os módulos. Define (A) um SLOT de segmentos na toolbar real do app (a toolbar do host aceita clusters de botões plugáveis) e (B) o SEGMENTO DE COLETA padrão que pluga nesse slot — debug/logs, screenshot, gravação tela+áudio, enviar pra Koder Observability, exportar tudo (kzip), limpar. É a face in-app do pipeline do Koder Kover (conector + captura + bundle + gate). NÃO é uma barra nova: é uma minibarra plugável na toolbar efetiva que o app já tem (protótipo: os botões na barra de endereços do Kruze). Surfaces sem toolbar (CLI/TUI) expõem a mesma capability via flag/ hotkey padrão — o contrato é a capability, não o pixel.

When this spec applies

Primary triggers

Adicionar coleta de dados in-app a um app Koder

All triggers

Adicionar a barra/segmento de coleta a um app Koder
Implementar o slot de segmentos na toolbar do koder_kit/koder_web_kit
Expor coleta de dados numa surface CLI/TUI
Extrair os botões de coleta do Kruze pro SDK

Two-part framework standard. (A) A Koder app's real toolbar exposes a standard segment slot that hosts pluggable button clusters. (B) The collection segment is the first standard segment — the in-app face of the Koder Kover pipeline. It is a mini-bar that plugs into the existing toolbar, not a new bar. Rules R*, tests T*.

Scope

Applies to every Koder app surface, in every module. GUI surfaces (mobile/desktop/web/tv) render the segment in their toolbar; non-toolbar surfaces (cli/tui) expose the same capability via a standard flag/hotkey. This spec is the contract; the SDKs implement it per surface (koder_kit, koder_web_kit, CLI flags, TUI). Enforced as a standard app behavior (behaviors.kmd §10) and audited by /k-parity across surface × module.

R1.1 — The Koder toolbar widget (koder_kit / koder_web_kit) MUST expose a standard segment slot: an ordered region that accepts pluggable segments (button clusters). A segment declares an id, an order hint, and its affordances; the host renders it inline in the real toolbar.

R1.2 — Segments are isolated: one segment's failure (or absence) MUST NOT break the toolbar or other segments. The slot is additive — apps with no segments render their toolbar unchanged.

R1.3 — The slot is reusable for future standard segments (share, AI, …), not collection-only. Collection is the first standard segment, not a special case.

R2 — The collection segment (the standard cluster)

R2.1 — The collection segment MUST offer this affordance set (hidden/ disabled where a surface cannot support one): debug, logs, screenshot, record (screen + optional audio), send (→ Koder Observability), export (→ kzip), clear.

R2.2 — Capture affordances MUST reuse engines/sdk/koder_capture_widgets_dart (recorder/level-meter/pre-flight/post-record-audit over kcap) — no second capture UI. export MUST produce a engines/compress/kzip archive.

R2.3 — send MUST route through the Koder Kover bundle + egress gate (products/dev/kover internal/bundle; KOVER-009): nothing is transmitted unless every artifact is redacted and consent-approved (R5).

R3 — Capability per surface (the contract is the capability, not the pixel)

Surface	Affordance form
mobile / desktop / web / tv	the collection segment plugged into the app toolbar (R1/R2)
cli	a standard flag (`--collect` / `--collect-bundle`), per `binaries-and-cli/standard-flags.kmd`
tui	a standard hotkey / command (e.g. a `:collect` palette command)

R3.1 — All surfaces drive the same underlying pipeline (Kover connector → capture → bundle → gate). Only the affordance differs. A surface that omits an affordance MUST declare it (not silently drop it).

R4 — Data model & storage (user's own quota)

R4.1 — Collected items map to the Kover taxonomy (protocol.kmd R3): logs/ errors/events via the connector; screen/video/audio as capture artifacts (capture.kmd). One collection session groups them by session_id.

R4.2 — Collected data is stored under the user's own storage quota on the object plane (stack-RFC-006; bytes by ref, records in kdb), multi-tenant per multi-tenant-by-default.kmd. It is the user's data, in their quota.

R4.3 — clear deletes a session's data (the "clean it later" action), bound by identity-data-retention.kmd (LGPD erasure) + tiered retention (capture.kmd R5).

R5 — Privacy gate (local-first, explicit consented egress)

R5.1 — Local-first. "Auto-store" means stored locally, in the user's quota — never auto-transmitted. Collection itself defaults off / per-session (mirrors errors/reporting.kmd auto-report default OFF).

R5.2 — Egress is explicit + gated. send is a distinct user action that MUST pass the consent + redaction gate (capture.kmd R-consent/R-redact via the Kover bundle). Screen/video carries PII/credentials/third parties — local- first + consented-send is non-negotiable on every surface.

R6 — Reuse / don't fork (the standard composes existing parts)

R6.1 — The segment subsumes and extends the errors/reporting.kmd "Report a problem" affordance (from report an error to collect + report) — same lineage, same services/foundation/reporter backend. It MUST NOT create a parallel report path.

R6.2 — Kruze's address-bar collection buttons are the prototype; the standard is realised by extracting them into the koder_kit segment slot, with Kruze as the first consumer of the standard slot.

R7 — Cross-cutting compliance

R7.1 — The segment is a Koder UI surface: it MUST emit OUIA hooks (ouia-test-hooks.kmd), use Verge tokens + light/dark, be i18n'd (language.kmd/i18n contract), be headless-testable (headless-first.kmd), and respect safe-area/topbar placement (app-layout/*).

Test cases

#	Check	Severity
T1	A toolbar with no segments renders unchanged; adding the collection segment inserts the cluster inline (R1.1).	hard
T2	A failing/absent segment does not break the toolbar or siblings (R1.2).	hard
T3	`send` refuses when any artifact is non-redacted or non-approved (routes through the Kover gate, R2.3/R5.2).	hard
T4	`export` yields a valid kzip of the session's collected data (R2.2).	hard
T5	Collection defaults off; nothing is transmitted without an explicit `send` (R5.1).	hard
T6	`clear` removes a session's stored data from the user's quota (R4.3).	hard
T7	A CLI surface exposes the capability via the standard flag; a TUI via the standard command (R3).	soft
T8	The segment emits OUIA hooks + passes the headless self-check (R7).	hard

Non-goals

The collection pipeline (connector/capture/bundle/gate) — owned by products/dev/kover + its specs. This spec is the in-app UI standard over it.
The object-storage substrate — stack-RFC-006.
Per-surface widget implementation — tracked in projects/koder-kit (KKIT).

Open questions

Final naming of the slot API + the segment (forms.kmd) — working names "toolbar segment slot" + "collection segment" (a.k.a. Kover segment).
Whether the slot belongs to a generic koder_kit Toolbar/AppBar widget or a dedicated host — decide at the slot ticket (KKIT).

References

meta/docs/stack/specs/koder-app/behaviors.kmd
meta/docs/stack/specs/errors/reporting.kmd
meta/docs/stack/specs/kover/capture.kmd
meta/docs/stack/specs/kover/protocol.kmd
meta/docs/stack/rfcs/kover-RFC-001-foundations.kmd
meta/docs/stack/specs/binaries-and-cli/standard-flags.kmd
meta/docs/stack/specs/testing/ouia-test-hooks.kmd
engines/sdk/koder_capture_widgets_dart
engines/compress/kzip
services/foundation/reporter
products/dev/kover