Skip to content

docs: update repo/developer/in-app docs and repair the screenshot pipeline for 2.8.0#5775

Merged
jamesarich merged 2 commits into
release/2.8.0from
docs/2.8.0-feature-docs
Jun 11, 2026
Merged

docs: update repo/developer/in-app docs and repair the screenshot pipeline for 2.8.0#5775
jamesarich merged 2 commits into
release/2.8.0from
docs/2.8.0-feature-docs

Conversation

@jamesarich

@jamesarich jamesarich commented Jun 11, 2026

Copy link
Copy Markdown
Collaborator

What

Brings documentation current with everything bundled in release/2.8.0 — the repo / agent docs and the hosted + in-app docs under docs/ — and repairs the screenshot pipeline that feeds both the Jekyll site and the in-app docs browser.

Grounded by a source-verified audit of the release branch, then an adversarial accuracy pass over the drafts that caught and corrected 4 over-claims: the App Functions settings entry is actually labeled "System AI" (not "App Functions"); Android Auto emergency alerts are not yet wired (emptyFlow()), so that section was removed; there is no canned-reply list (voice/text reply only); and the Discovery AI summary is not flavor-gated (ships on all Android builds, AI-vs-algorithmic depends on on-device model availability).

Commit 1 — doc content (ced62d911)

Repo / agent docs

  • Remove the obsolete git submodule update --init proto-submodule bootstrap (proto is the org.meshtastic:protobufs Maven dep since Replace :core:proto with org.meshtastic:protobufs:2.7.25 #5675) from CLAUDE.md, .skills/project-overview, .skills/new-branch; reword the AGENTS.md "Never Touch Protos" rule.
  • README.md: drop the dead core/proto row; add feature/discovery, feature/car, baselineprofile; add a 2.8.0 Features section.

Developer docs (docs/en/developer)

  • Remove core:proto / core:api from the module maps; add feature:discovery, feature:car, baselineprofile, screenshot-tests.
  • Add the PacketFts FTS5 table to persistence; add a Baseline Profile section to testing; refresh "What's New for Developers"; fix the screenshot task name.

User / in-app / hosted docs (docs/en/user)

Page Change Feature
discovery.md New Local Mesh Discovery scanner section + fix contradictory line #5275
node-metrics.md Air Quality metrics (PM1.0/2.5/10, CO₂ severity bands) #5701
messages-and-channels.md Full-text message search #5373
android-auto.md (new) Android Auto guide #5633
app-functions.md (new) App Functions / System AI guide #5585
desktop.md, user.md feature-parity rows + What's New entries

The two new pages are wired into the in-app docs browser (DocBundleLoader.kt + DocPageIconResolver.kt + 4 string resources). nodes.md already documented msh.to device links (#5714/#5765).

Commit 2 — screenshot pipeline repair + 2.8.0 feature screenshots (1f66dbf87)

A checksum-verified audit of the screenshot pipeline found it substantially broken:

  1. In-app images never rendered. Pages reference ../../assets/screenshots/… but ComposeResourceImageTransformer built an unnormalized files/docs/../../… path and silently swallowed the miss — every page in the in-app reader was imageless. Fix: the resolver anchors assets/… links at files/docs/, and a new DocImageWiringTest fails the build if any doc-page image doesn't resolve to a bundled resource.
  2. The bundle shipped the wrong directory: ~4 MB of raw unaliased CST renders nobody references, while 9 markdown-referenced images were missing in-app. Fix: docs/assets/screenshots/ (tracked, semantic names) is now the single source for the Jekyll site and the in-app bundle; copyDocsScreenshots refreshes it, copying only alias-mapped light-mode reference images.
  3. 6 aliases pointed at the wrong component (telemetric_actions→ElevationInfo, quick_chat→ChannelInfo, detail_local→DeviceListItem, detail_section→AppInfoSection, position→SatelliteCount, environment_metrics→a dark-mode SignalInfo render) and 2 at deleted previews — any regeneration would have clobbered good images with wrong ones. All corrected; missing mappings added. (connections_wifi_* remain manual captures until matching previews exist.)

New deterministic previews with mock data

Wired into screenshot-tests and embedded in the doc pages: discovery preset-result card + dwell progress (feature/discovery, new module dep + manifest entry), air-quality metric cards (feature/node), message search bar (feature/messaging), App Functions settings (feature/settings). Android Auto stays text-only (Car App Library templates aren't Compose).

Drive-by bug fix caught by the new preview

AirQualityMetricsCard (new in 2.8.0, #5701) rendered its timestamp and PM rows stacked on top of each otherSelectableMetricCard's SelectionContainer imposes no layout. Now wrapped in a Column like its environment-metrics sibling, with a timeTextOverride preview seam for deterministic renders.

Verification

  • Commit 1: spotlessApply spotlessCheck detekt :feature:docs:allTests green; full PR CI green on ced62d911 (12 pass / 0 fail).
  • Commit 2: spotlessApply spotlessCheck detekt :screenshot-tests:updateDebugScreenshotTest + copyDocsScreenshots + validateDebugScreenshotTest (317 screenshot tests) + :feature:docs:allTests (incl. the new DocImageWiringTest) + :feature:node:allTests — all green locally; PR CI running.

Targets release/2.8.0 (not main).

🤖 Generated with Claude Code

Bring documentation in line with the features bundled in release/2.8.0 and
the proto submodule -> org.meshtastic:protobufs Maven migration.

Repo / agent docs:
- Drop the obsolete `git submodule update --init` proto-submodule bootstrap
  from CLAUDE.md, .skills/project-overview, and .skills/new-branch, and reword
  the AGENTS.md "Never Touch Protos" rule (protos are now a Maven dependency).
- README: remove the dead core/proto module row; add feature/discovery,
  feature/car, and baselineprofile; add a 2.8.0 Features section.

Developer docs (docs/en/developer):
- Remove core:proto / core:api from the module maps; add feature:discovery,
  feature:car, baselineprofile, and screenshot-tests.
- Add the PacketFts FTS5 table to persistence; add a Baseline Profile section
  to testing; refresh "What's New for Developers"; fix the screenshot task name.

User / in-app / hosted docs (docs/en/user):
- discovery.md: document the new Local Mesh Discovery scanner (#5275) and fix
  the now-contradictory "no dedicated discovery mode" line.
- node-metrics.md: add Air Quality metrics (PM1.0/PM2.5/PM10, CO2) (#5701).
- messages-and-channels.md: add full-text message search (#5373).
- New android-auto.md (#5633) and app-functions.md (#5585) pages, wired into the
  in-app docs browser (DocBundleLoader + DocPageIconResolver + string resources).
- desktop.md feature-parity rows and user.md "What's New" entries.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Jun 11, 2026
@jamesarich jamesarich added this to the 2.8.0 milestone Jun 11, 2026
…dd 2.8.0 feature screenshots

In-app rendering was silently broken: doc pages reference images as
`../../assets/screenshots/...` but ComposeResourceImageTransformer built an
unnormalized `files/docs/../../...` path, so no screenshot ever resolved in
the in-app reader. The resolver now anchors `assets/...` links at
`files/docs/`, and a new DocImageWiringTest asserts every image referenced by
a bundled page resolves to a real bundled resource.

Screenshot assets are now single-sourced from the tracked
docs/assets/screenshots/ directory: syncDocsToComposeResources bundles it
directly (previously it bundled the untracked docs/screenshots staging dir —
~4 MB of raw, unaliased CST renders that no page referenced, while 9
referenced images were missing in-app), and copyDocsScreenshots refreshes it,
copying only alias-mapped light-mode reference images.

Alias map corrections (each previously pointed at the wrong component or a
deleted preview): telemetric_actions, detail_local, detail_section,
quick_chat, environment_metrics, position; removed two dangling entries;
added mappings for previously manual assets (disconnect, firmware_error,
messages_reaction, docs-browser_*, app_info, persistence). The
connections_wifi_* captures remain manual until matching previews exist.

New deterministic previews with mock data, wired into screenshot-tests and
referenced from the docs: air-quality metric cards (feature/node), message
search bar (feature/messaging), App Functions settings (feature/settings),
and discovery preset-result card + dwell progress (feature/discovery, new
module dep + manifest entry). Android Auto has no Compose surface (Car App
Library templates), so it stays text-only.

The new air-quality preview exposed a real layout bug in the 2.8.0
AirQualityMetricsCard: SelectableMetricCard's SelectionContainer imposes no
layout, so the timestamp and PM rows rendered stacked on top of each other.
The card content is now wrapped in a Column like its environment-metrics
sibling, with a timeTextOverride preview seam for deterministic renders.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@jamesarich jamesarich changed the title docs: update repo, developer, and in-app docs for the 2.8.0 release docs: update repo/developer/in-app docs and repair the screenshot pipeline for 2.8.0 Jun 11, 2026
@jamesarich jamesarich merged commit befa7fb into release/2.8.0 Jun 11, 2026
17 checks passed
@jamesarich jamesarich deleted the docs/2.8.0-feature-docs branch June 11, 2026 17:01
jamesarich added a commit that referenced this pull request Jun 12, 2026
…eline for 2.8.0 (#5775)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
jamesarich added a commit that referenced this pull request Jun 13, 2026
…eline for 2.8.0 (#5775)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant