trail-mate/docs/specification/SETTINGS_ARCHITECTURE_REFACTOR_SPEC.md

Settings Architecture Refactor Specification

Status date: 2026-07-09

本文档定义 Trail Mate settings 的下一阶段改造规格。它不是一次小修小补的 UI 整理，而是把“配置是什么、属于哪个协议、如何展示、如何持久化、如何从 SD 恢复、如何 应用到运行时”重新拉直。

本规格先落地文档，不改变运行时代码。实际实现必须按本文分阶段推进，并在修改任何 函数、类或方法前按仓库规则做 GitNexus impact analysis。

User Goal

目标用户场景是 Trail Mate 可以脱离手机工作：

• 选择 Meshtastic、MeshCore 或 Reticulum 后，settings 只展示该协议真正相关的项目。
• Meshtastic 的 MQTT 只服务 Meshtastic；MeshCore 的 MQTT 只服务 MeshCore；两者不互通。
• MQTT 只支持轻负担模式：不实现 TLS，不实现额外 MQTT payload 加密层。
• MQTT 启用是显式配置；Wi-Fi 关闭时 runtime 必须停 MQTT，Wi-Fi 开启时不得自动把 MQTT 配置改成启用。
• 如果某个协议配置了 MQTT 并且 runtime 正在使用 Wi-Fi MQTT transport，该协议对应的 BLE phone dependency 应被压低或关闭，避免用户误以为还必须连手机。
• 所有用户配置都必须可持久化，并能从 SD 备份恢复。
• 备份恢复不能为了“人类可读”牺牲 ESP 内存安全；当前整包 JSON/cJSON 模式需要替换。

Distinctions

这些概念必须在代码和 UI 中分开，不能继续混在 Chat / Network 两个大筐里。

Concept	Meaning	Must not be confused with
Protocol	Meshtastic、MeshCore、Reticulum 的协议语义和节点身份体系	transport、radio preset、UI 页面
Radio profile	LoRa 频点、带宽、扩频因子、编码率、tx power、region/preset	channel name、PSK、broadcast/private
Channel / group	协议内的群组、slot、topic 或 destination 配置	空口参数
Transport	LoRa、BLE phone link、Wi-Fi MQTT、Reticulum TCP/UDP 等承载方式	protocol 本身
Conversation	UI 里的广播会话、私聊会话、联系人上下文	Meshtastic channel slot 或 MeshCore channel slot
Device settings	屏幕、语言、GPS、地图、Wi-Fi、owner name、隐私等跨协议设置	当前 active protocol 的 profile
Persistence	NVS/Preferences/IDF store/SD backup 的落盘事实	UI widget state
Apply runtime	把配置变更应用到 radio、MQTT、BLE、GPS、privacy policy	保存配置

Channel, Radio, Broadcast, Private

空口参数决定“谁能在 RF 层听见谁”：频率、带宽、扩频因子、编码率、tx power、region 或 preset 必须兼容，两个设备才可能互相收发 LoRa frame。

Channel/group 决定“收到 frame 后属于哪个协议群组或密钥域”：Meshtastic 使用 channel slot/name/key/hash，MeshCore 使用 channel slot/name/key/public-channel fallback，Reticulum 使用 destination、announce、interface 和 identity。它们不是同一种对象，不能做一个泛化的 channel 然后让三个协议硬套。

广播和私聊是寻址语义：广播表示发给当前协议/channel/group 中的所有可见节点；私聊表示 发给一个 node id、destination 或 peer，并可能涉及 ack、route、retry、session 状态。广播 或私聊不改变空口参数，也不自动创建 channel。

MQTT 是 transport，不是第四种协议，也不是跨协议桥。Meshtastic MQTT 下来的 Meshtastic packet 应走 Meshtastic 接收路径；MeshCore MQTT 下来的 MeshCore packet 应走 MeshCore 接收 路径。二者没有互通要求。

Current Code Inventory

本节记录当前实现事实，作为改造前的基线。

Area	Current owner	Observed shape
Global config aggregate	modules/core_sys/include/app/app_config.h	AppConfig 同时承载 device、chat、GPS、map、privacy、Meshtastic、MeshCore、Reticulum、MQTT、legacy channel 字段
Protocol config object	modules/core_chat/include/chat/domain/chat_types.h	chat::MeshConfig 被三个协议复用，里面同时有 radio、Meshtastic channel、MeshCore channel、MQTT、Reticulum group/interface 字段
Shared LVGL settings	modules/ui_shared/src/ui/screens/settings/settings_page_components.cpp	kChatItems / kNetworkItems 混合协议项，通过 pref_key 字符串和 should_show_item 做隐藏
Shared settings state	modules/ui_shared/include/ui/screens/settings/settings_state.h	一个大 UI state 同时缓存 chat、network、MT MQTT、MC MQTT、Reticulum、device 字段
Mono settings	modules/ui_mono/src/runtime.cpp	保留大量 MT/MC 设置处理代码，但当前 radio item list 只暴露少数入口，能力与 UI 展示不一致
GTK settings	apps/linux_uconsole_gtk/src/platform/gtk/gtk_uconsole_settings_logic.cpp	已有按协议 stack/page 切换的雏形，可作为“协议页”思路参考，但不应直接复制 GTK widget 逻辑
Arduino ESP persistence	platform/esp/arduino_common/src/app_config_store.cpp	使用 Preferences 按字段保存，大量 key 已存在，但字段覆盖靠手写 load/save 保持同步
IDF persistence	apps/esp32_lvgl/src/esp32_lvgl_idf_app_facade_runtime.cpp	把整个 AppConfig 包进 raw blob，按 sizeof(AppConfig) 判断版本，结构一变旧配置就会被拒绝
SD settings backup	platform/esp/arduino_common/src/platform_ui_settings_backup_runtime.cpp	当前 path 是 /trailmate/settings-backup.json，用 cJSON 构造/解析整棵树，并读入整文件
Store API	modules/core_sys/include/platform/ui/settings_store.h	同时提供 get_blob(std::vector<uint8_t>&) 和 get_blob_into(...)；新 ESP 路径应优先使用 bounded buffer 版本
Apply facade	modules/core_sys/include/app/app_facades.h	UI 可直接拿 getConfig() 修改，再调用 saveConfig()、applyMeshConfig()、applyUserInfo() 等 apply 方法

Problems

1. Settings taxonomy is wrong

Chat 与 Network 现在不是产品概念，而是历史容器。结果是：

• Meshtastic MQTT、MeshCore MQTT、Reticulum Wi-Fi interface 都可能出现在同一类页面里。
• chat_psk 这种名字无法表达它到底是 Meshtastic channel key 还是 MeshCore channel key。
• 用户选择协议后仍会看到另一个协议的残留项，或者必须靠 string blacklist 隐藏。
• 新增 channel management 时无法自然表达 “Meshtastic channel slot” 与 “MeshCore channel slot”。

2. Config ownership is too broad

AppConfig 和 MeshConfig 目前是运行期大对象。它们可以作为过渡兼容层，但不能继续作为 长期 settings schema。原因：

• 字段归属不清，导致 UI、Preferences、SD backup、协议 apply 都各自记一份事实。
• ESP stack hygiene 已把 AppConfig、MeshConfig 列为危险 automatic local 类型。
• 新增 channel 列表或更多协议 profile 时，如果继续塞进这两个 struct，会持续放大内存风险。

3. Persistence is not schema-driven

Arduino Preferences 当前按字段保存，比 raw blob 稳定，但每个字段需要手写 load/save、默认值、 迁移逻辑。新增一个 settings 字段时，很容易漏掉 SD backup 或某个 UI。

IDF raw blob 以 sizeof(AppConfig) 为兼容条件，这对后续拆分结构非常脆弱。任何 AppConfig 布局变化都可能导致旧配置无法加载。

4. SD JSON backup is too heavy

当前 JSON 方案的优点是可读，但在 ESP 上代价偏大：

• restore 需要把整个文件读进内存。
• cJSON parse 会构造整棵树。
• backup print 会生成完整字符串。
• 旧代码中存在 std::string、std::vector<uint8_t>、whole-document parse/print 的组合。

这与“配置可完整落 SD，并能可靠恢复”的目标相冲突。恢复配置应该是低内存路径，而不是 最容易把设备推到 heap/stack 边界的路径。

5. Apply semantics are scattered

UI 直接改 getConfig()，再按字段手动调用不同 apply 方法。这样很难保证：

• 修改协议时，BLE/MQTT/LoRa/runtime 状态都按同一套规则切换。
• Wi-Fi 关闭只停 MQTT runtime，不悄悄改用户配置。
• MQTT 成功上行时 UI 不再只等 LoRa 成功才算 sent。
• 从 MQTT 收到的节点和 LoRa 收到的节点进入同一 contact/nearby/chat projection。

这些问题已经在 MQTT 调试中暴露过，settings refactor 需要把 runtime impact 作为字段元数据 的一部分，而不是散落在回调里。

Target Architecture

Layer Shape

目标结构如下：

Settings UI
  -> SettingsDescriptor tables
  -> SettingsEditSession / field-level draft
  -> SettingsTransaction
  -> SettingsValidator + normalizer
  -> SettingsPersistence
  -> RuntimeApplyDispatcher
  -> Protocol/runtime adapters

AppConfig 在第一阶段继续存在，但应降级为 compatibility backing store，不再作为 settings schema 的唯一事实来源。

Domain Buckets

长期结构应把配置分成这些 owner：

Owner	Examples
DeviceSettings	owner long/short name、locale、screen、time、battery/display policy
ConnectivitySettings	Wi-Fi credentials、Wi-Fi enable policy、network limits
GpsMapSettings	GPS power/publish policy、map tile/cache/source、tracker defaults
PrivacySettings	ignored nodes、contact alert policy、location visibility
MeshtasticProfile	radio preset、region、hops、node info、channels、Meshtastic MQTT
MeshCoreProfile	radio profile、channel slot/name/key、public-channel fallback、MeshCore MQTT
ReticulumProfile	identity、LoRa interface、Wi-Fi interface、LXMF/announce groups
ChatPresentationSettings	active conversation defaults、notification/presentation preferences
BackupRestoreSettings	backup version、restore policy、sensitive export policy

这些 owner 可以先映射到现有 AppConfig 字段，但 schema 命名必须先按 owner 设计，避免未来 继续把三种协议塞回 Chat / Network。

Settings Descriptor

每个可展示/持久化的 field 必须有一条静态 descriptor。descriptor 应该是小的 constexpr 表项，避免动态分配和重型 callback。

建议 descriptor 至少包含：

Metadata	Purpose
stable field id	编译期 enum，不用任意字符串做业务判断
owner/profile	device、connectivity、mt、mc、reticulum 等
UI section	决定显示在哪个协议页或设备页
type	bool、u8、i32、enum、bounded string、hex blob、secret
bounds	字符串最大长度、数值范围、blob 最大长度
protocol mask	MT/MC/Reticulum/global 的可见性
capability mask	板子是否支持 Wi-Fi、BLE、GPS、LoRa、SD
runtime impact	none、save-only、apply-mesh、apply-user、apply-gps、restart-mqtt、restart-ble
storage key	NVS key、SD key、legacy key
default provider	按协议/地区/板型给默认值
migration rule	从旧 key、旧 blob、旧 JSON 恢复时如何写入
sensitive flag	PSK、MQTT password、Wi-Fi password 等

UI 层只消费 descriptor 和当前 protocol/capability，不能再写 if (pref_key == "...") 作为主要 可见性规则。

Protocol-Specific UI

Settings 顶层建议拆为：

• Device
• Connectivity
• Protocol
• Channels
• MQTT
• GPS & Map
• Privacy
• Backup & Restore
• Diagnostics

其中 Protocol、Channels、MQTT 的内容由 active protocol 决定。

Meshtastic 页面应展示：

• Meshtastic radio preset/region/modem preset/hops/tx power。
• Meshtastic channel slots。第一阶段可继续 primary/secondary，schema 必须预留 slot list。
• Meshtastic MQTT：enabled、preset、host、port、username、password、root topic、uplink/downlink。
• BLE phone link policy：当 Meshtastic MQTT runtime 可用时，BLE 可被关闭或降级。

MeshCore 页面应展示：

• MeshCore radio profile/region/channel slot/tx power。
• MeshCore channel name/key/public channel fallback。
• MeshCore MQTT：enabled、preset、host、port、username、password、root topic、uplink/downlink。
• MeshCore contact/nearby projection 必须与 LoRa receive 一样处理 MQTT receive 的节点。

Reticulum 页面应展示：

• Reticulum identity/status。
• LoRa interface 参数。
• Wi-Fi interface 参数。
• LXMF/announce groups。
• 不展示 MQTT，因为当前目标不包含 Reticulum MQTT。

MQTT Policy

MQTT 是 protocol-scoped transport：

MeshtasticProfile.mqtt -> Meshtastic MQTT runtime only
MeshCoreProfile.mqtt   -> MeshCore MQTT runtime only

运行态 eligibility：

configured = profile.mqtt.enabled && host not empty && port > 0
eligible = configured && wifi_runtime.connected && protocol == active_protocol

约束：

• wifi_runtime.connected == false 时必须 stop MQTT runtime。
• Wi-Fi 变为 connected 时，只能让已经启用且配置完整的 MQTT runtime 变为 eligible；不得自动把 profile.mqtt.enabled 从 false 改为 true。
• Plain MQTT only：tls=false 是唯一支持形态；UI 不提供 TLS 开关，代码也不引入 TLS 客户端。
• MQTT username/password 可支持，因为它不是 TLS；但必须按 secret 字段处理。
• MQTT receive 必须进入与 LoRa receive 相同的协议 projection：chat message、delivery status、 contacts/nearby、node info、position、notification。
• MQTT uplink 成功不能被 LoRa TX 失败覆盖成 failed；delivery outcome 应区分 transport。

Default Presets

默认 MQTT preset 不能以个人 broker 作为默认值。默认表应是协议 owner 的一部分：

Protocol	Default preset intent
Meshtastic	mainstream Meshtastic public MQTT preset, plaintext transport, default root/topic/channel matching current community convention
MeshCore	mainstream MeshCore public/community preset if available; otherwise disabled with empty custom host until用户选择 preset

实现时不把某个个人域名硬编码成默认。个人 broker 可以存在于 custom preset 或用户配置里。

SD Backup Format

Decision

新格式默认不使用 JSON。

采用 line-oriented typed key-value 格式，目标是：

• 可人工检查。
• 可流式读取。
• 每次只需要一个 bounded line buffer。
• 不需要 cJSON tree。
• 不需要把整个文件读入 std::string。
• 不需要 std::vector<uint8_t> 承接 whole blob。

建议文件名：

/trailmate/settings-backup.tms
/trailmate/settings-backup.tmp

.json 旧文件可以在迁移期作为 legacy restore input，但新备份写出必须使用 .tms。

Format Sketch

TMSET2
schema.version=u16:2
created.unix=u32:1783500000
device.owner.long=str:Trail Mate
device.owner.short=str:TM
protocol.active=enum:meshtastic

mt.radio.region=enum:CN
mt.radio.modem_preset=enum:LONG_FAST
mt.channel.0.name=str:LongFast
mt.channel.0.psk=hex:01020304...
mt.mqtt.enabled=bool:1
mt.mqtt.host=str:mqtt.meshtastic.org
mt.mqtt.port=u16:1883
mt.mqtt.root=str:msh/CN
mt.mqtt.username=str:meshdev
mt.mqtt.password=secret:large4cats

mc.channel.slot=u8:0
mc.channel.name=str:public
mc.channel.key=hex:
mc.mqtt.enabled=bool:0

checksum.crc32=hex:89ABCDEF

Rules:

• First line is magic: TMSET2.
• Max line length is fixed, initially 256 or 384 bytes. Any longer line is skipped with a diagnostic.
• Key is ASCII stable storage key.
• Type prefix is mandatory.
• Strings are bounded by descriptor metadata.
• Hex blob max length is bounded by descriptor metadata before decoding.
• Unknown keys are ignored but counted.
• Known key with invalid value is rejected and reported, not partially applied.
• Restore writes through SettingsTransaction; it must not directly mutate random globals.
• Backup write uses temp file + fsync/close + rename where backend supports it.
• CRC covers all lines before checksum.

Why Not Binary TLV First

Binary TLV is smaller and faster, but it is harder to inspect and repair on SD. The line KV format is the better first target because it keeps manual recovery possible without the cJSON memory cost. A future binary TLV export can be added for factory/provisioning use, but it should not be the only user backup format.

Sensitive Fields

为了满足“完全从 SD 恢复”，Wi-Fi password、MQTT password、channel PSK 应可进入备份。UI 必须 把这些字段标记为 sensitive，并在手动导出/恢复界面给出明确提示。

实现上 sensitive 只影响 UI 呈现和日志脱敏，不意味着不落盘。用户选择 SD backup 时，目标是 恢复一台离线设备的完整配置。

Persistence Model

每个字段必须通过同一份 descriptor 声明其持久化位置。

Arduino Preferences

现有 Preferences key 可以保留，但 schema 要成为覆盖清单：

• load 时按 descriptor 读 key，应用 default/migration。
• save 时按 descriptor 写 key。
• 对 blob/secret 使用 bounded buffer。
• 对旧 key 做一次 migration，不在 UI 回调里散写兼容逻辑。

IDF Store

raw sizeof(AppConfig) blob 只能作为 legacy input。新路径必须是版本化字段 store：

• 读取旧 raw blob 时，迁移到 schema field store。
• 新保存不再依赖 sizeof(AppConfig)。
• 如果为了启动速度保留 compact snapshot，也必须有独立 schema version 和 field-level fallback。

SD Backup

SD backup 是 cross-store restore source，不是运行时唯一 store。启动时不应每次从 SD 覆盖 NVS。 恢复应该是显式动作：

User chooses Restore
  -> parse .tms stream
  -> validate descriptors
  -> build transaction
  -> persist to primary store
  -> apply affected runtimes
  -> emit UI result

Memory Budget Rules

实际实现必须遵守：

• 不在 ESP task stack 上创建 AppConfig、chat::MeshConfig、protobuf frame、大 byte array。
• Settings UI edit session 不复制整份 AppConfig；只保存 field-level dirty value 或 active editor buffer。
• SD restore 不读完整文件，不构造树，不用 cJSON_ParseWithLength 作为新路径。
• 不引入 std::deque 到 ESP BLE/Meshtastic bridge headers。
• 新 schema table 使用 static/constexpr storage。
• 新 channel list 使用固定上限和显式 drop/error policy，不能无界增长。
• 大字符串格式化使用 caller-provided buffer 或小 scratch owner，不把临时大对象放在回调栈上。

Packaged Delivery Plan

This refactor is delivered as one cohesive feature package, not as user-visible partial phases. The steps below are an internal construction sequence only. The final deliverable must include schema, protocol-aware UI, persistence, SD backup/restore, runtime apply behavior, tests and verification together.

No intermediate state should be considered complete if it leaves settings half migrated, exposes new protocol pages without matching persistence, or writes a new SD backup format without restore.

Slice 0: Specification and Audit

Deliverables:

• 本文档。
• 当前 settings/persistence/apply 代码清单。
• 确认 JSON 备份替换方向。

No runtime behavior change.

Slice 1: Descriptor Read Model

Introduce descriptor tables and read accessors without changing existing UI behavior.

Deliverables:

• SettingsFieldId enum。
• protocol/global owner metadata。
• field descriptors for all currently visible settings。
• tests that every field has default, storage key, owner, visibility, runtime impact。

Compatibility:

• Existing AppConfig remains backing store。
• Existing LVGL settings can still use old state while descriptors are validated in tests。

Slice 2: Transaction and Apply Dispatcher

Move settings mutation through a small transaction boundary.

Deliverables:

• field-level set/get APIs。
• validator/normalizer。
• runtime impact diff。
• dispatcher that calls applyMeshConfig()、applyUserInfo()、applyPositionConfig()、 MQTT restart/stop and BLE policy in one place。

Compatibility:

• Existing UI callbacks can be converted incrementally field by field。

Slice 3: Protocol-Aware UI Sections

Replace kChatItems / kNetworkItems as primary organization.

Deliverables:

• Device/Connectivity/Protocol/Channels/MQTT/GPS & Map/Privacy/Backup sections。
• Active protocol filter from descriptor metadata。
• Board capability filter from descriptor metadata。
• No business visibility based on pref_key string comparisons。

Acceptance:

• Selecting Meshtastic shows Meshtastic channel/MQTT/radio settings only。
• Selecting MeshCore shows MeshCore channel/MQTT/radio settings only。
• Selecting Reticulum shows Reticulum interface/group settings and hides MQTT。

Slice 4: Lightweight SD Backup

Replace default JSON backup writer/reader with .tms.

Deliverables:

• streaming writer。
• streaming parser。
• fixed max line length。
• CRC。
• descriptor-backed export/restore coverage。
• legacy .json restore either removed or isolated behind explicit compatibility path with strict size cap。

Acceptance:

• Full settings backup/restore succeeds without whole-file allocation。
• Unknown future keys are ignored safely。
• Sensitive fields restore correctly and logs are redacted。

Slice 5: Channel Management

Introduce protocol-specific channel/group management.

Deliverables:

• Meshtastic channel slot model。
• MeshCore channel slot model。
• Reticulum group/destination model remains separate。
• Create/join/share flow for supported protocols。
• QR/import/export payload generation on demand, using bounded scratch storage。

Acceptance:

• Creating a Meshtastic channel does not mutate MeshCore fields。
• Creating a MeshCore channel does not mutate Meshtastic fields。
• Broadcast/private conversation selection references protocol-specific channel identity explicitly。

Slice 6: Retire Raw Struct Persistence

After migrations are covered by tests and field store is proven:

• Stop writing raw AppConfig blobs。
• Keep one-way read migration for a bounded release window。
• Remove legacy keys only after backup/restore and migration tests prove no supported user path is lost。

Package Acceptance

The package is not done until all of these are true:

• Protocol selection changes visible settings, stored settings and runtime apply behavior together。
• Meshtastic, MeshCore and Reticulum each have their own settings surface; hidden fields are hidden by descriptor/capability metadata, not by ad hoc string checks。
• Meshtastic MQTT and MeshCore MQTT can be configured independently and are persisted/restored。
• Wi-Fi off stops MQTT runtime; Wi-Fi on does not auto-enable MQTT config。
• SD backup writes .tms, restore reads .tms, and all user settings covered by descriptors round trip。
• Legacy Preferences/IDF/raw config paths migrate into the new schema without losing existing user settings。
• Settings UI does not create new large ESP stack objects or whole-config drafts。
• Tests and stack hygiene checks pass for the touched areas。

Verification Requirements

Before implementation PR/commit:

• Run GitNexus impact analysis before each edited symbol, and warn before HIGH/CRITICAL edits。
• Run unit tests for descriptor coverage, migration, transaction diff and backup restore parser。
• Run python3 scripts/check_esp_stack_hygiene.py when touching settings save/load, ESP BLE, Meshtastic bridge, or app config code。
• For PlatformIO build/upload/monitor, use background process + log polling as required by repo rules。
• Run detect_changes() before commit to verify affected symbols and flows。

Suggested tests:

Test	Purpose
descriptor coverage snapshot	every field has owner, protocol visibility, storage key, default, impact
protocol visibility matrix	MT/MC/Reticulum show different settings
legacy Preferences migration	existing NVS keys map to schema fields
IDF raw blob migration	old raw config can migrate once
.tms round trip	export -> restore produces equivalent config
.tms malformed input	long line, bad type, bad hex, unknown key, bad CRC handled safely
MQTT policy matrix	Wi-Fi off stops runtime; Wi-Fi on does not enable config; protocol switch stops old runtime
contact projection parity	MQTT receive and LoRa receive update contacts/nearby through same app event path

Explicit Non-Goals

• 不做 Meshtastic 与 MeshCore MQTT 互通。
• 不为 MQTT 增加 TLS。
• 不把 Reticulum 伪装成 MQTT/channel 页面。
• 不把一个 generic Channel 类型强塞给三种协议。
• 不在新备份路径使用 whole-document JSON。
• 不继续用 raw sizeof(AppConfig) 作为新持久化格式。
• 不为了快速 UI 隐藏继续扩大 pref_key string blacklist。
• 不把大量 channel 或 QR/share payload 常驻塞进 AppConfig。

Open Decisions

Decision	Recommendation
.tms max line length	Start at 256 bytes; allow 384 only if current MQTT/password fields need it
Legacy JSON restore	Keep one release as explicit compatibility restore with strict size cap, then remove
MeshCore public MQTT preset	Verify upstream/community default before hardcoding; otherwise default disabled with preset picker
Meshtastic channel slot count	Implement current primary/secondary first, schema list-ready
IDF protocol support	Current IDF runtime appears Meshtastic-only; full protocol UI must either expose capability limits or implement MC/RT there first
Sensitive backup UX	Default to full restore capability, with explicit warning/redaction rather than silently omitting secrets

Implementation Guardrail

Even though this is a single packaged feature, implementation should still proceed in a safe internal order. The first code change after this spec should not rewrite all settings UI at once. The safest opening move is:

1. Add schema field IDs and descriptor coverage tests.
2. Map descriptors to existing AppConfig read paths.
3. Add protocol visibility tests for MT/MC/Reticulum.
4. Only then start moving UI sections and persistence writers.

This keeps the refactor observable during development while still packaging the final user-facing result as one complete settings architecture change.