[VolkerChristian]

Latest review revision

Preview this revision

Broaden shared contribution guidance without confusing product contributions with control-repository work; update the verified native/browser CodexUI identity; record the aligned editorial frame and regenerate the organization profile.

Based on a completed read-only Claude review of all five previews and their reachable guides, followed by source verification of CLI options, listener/access behavior, dependency paths and release availability. This update supersedes earlier location-specific and docs-only statements below where the approved AISuite fix applies.

Shared invariant: common menu semantics and section depth; one authored owner for each procedure; complete first successes, safety meaning and material qualifications remain reachable. Original banners and existing figures remain byte-identical. No Landingpages artwork is used. Topic guides have return navigation, not duplicate self-linking README menus. Install stays a concise prose chooser; Build goes directly to the authoritative guide.

Verification

• Catalog check, 31 control tests, and freshly rendered profile drift comparison pass.
• 42 changed Markdown pages checked using GitHub Markdown rendering/slug semantics: local links, anchors, images, menu destinations, heading order and retained example content.
• Light/dark, desktop/mobile local render previews inspected; new mobile SVG contrast is at least 5.60:1. These approximate GitHub styling, not pixel-perfect production CSS.
• AISuite Release build succeeds with 14 build jobs; 34/34 CTest tests pass, including real isolated app-server transport and mocked provider coverage. An initial overlong evidence-build directory exceeded Unix socket path limits; the unmodified full suite passed from a shorter build directory. No tests were weakened or skipped.
• No billable live provider run or full CodexUI native/UI/hardware qualification is claimed. Existing whole-file AISuite clang-format findings are unchanged; unrelated formatting was not rewritten.

Boundaries

Only the five approved README collections/control presentation files and the separately approved AISuite client default/test are changed. No workflow definitions, package pipeline, SDK publication, secrets, licenses, release tags, other repositories or manually dispatched Actions runs. Merged after explicit maintainer approval. Existing SNode.C/MQTTSuite API URLs remain live and unchanged; replacement/retirement belongs to Phase 5. Deferred CodexUI/AutoTalk test fixes remain deferred.

Previous revision details (historical; latest revision above takes precedence)

Scope and governing invariant

Shared presentation without losing repository-specific content. Only the organization profile and the existing README collections of snode.c, mqttsuite, AISuite and CodexUI are included in this stage. No other repository receives the frame. No workflows, build manifests, package pipelines, secrets, license files or tags change. No workflow is manually dispatched.

This is an editorial presentation step, not automatic README enrollment. Marker ownership boundaries are prepared; cross-repository README sync/conformance automation is not enabled. The existing inline content takes precedence over the original three-screen length aspiration.

Built

• Keep the existing deterministic catalog-driven organization profile and original SNode.C mark; add plain-Markdown area navigation, kind labels and catalog dependency links.
• Preserve every catalog row, summary, note, release reference, fork parent and archive placement; print no project count on the page.
• Verify current CI workflow URLs through the GitHub API, including replacing the removed AutoTalk native-workflow URL in the organization snapshot only. AutoTalk's README is untouched.
• Document the narrowly scoped README frame, preserved-content map and verification boundaries in templates/readme-frame.md and PHASE4.md.
• No artwork from SNode.C-Landingpages is imported. No product release/site/packaging behavior is modified.

Local checks

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
python tools/snodec_sync check
python tools/snodec_sync profile
python -m unittest discover -s tests -v
python tools/snodec_sync profile --output /tmp/snodec-profile.md
diff -u profile/README.md /tmp/snodec-profile.md
git diff --check

All 31 unit/boundary tests, catalog validation and deterministic drift check passed locally. CMake, Ninja, Git and a C++ compiler are required by the existing workflow boundary tests. Added assertions cover navigation, kind labels and dependency links without removing existing assertions.

Preservation and visual verification

Across the four companion README PRs, all 50 original fenced examples, all 59 legacy anchors and all 140 original tracked docs/media files remain; original docs/media are byte-identical. Authored prose, lists, tables, commands, warnings, license statements and banner references were audited against each default-branch baseline. All local file/fragment checks passed. GitHub GFM-rendered HTML was reviewed with local Chrome layout previews at 1280px and 390px in both themes, using a local stylesheet (not an exact live-GitHub-CSS claim). These are presentation checks, not new product build/UI qualification.

Line accounting

Production Python across this PR: +7 / -7 (net zero). Test assertions: +25 / -0. Remaining changes are generated Markdown, verified metadata and documentation. No new production automation or competing registry is introduced.

Existing summaries awaiting maintainer confirmation

The catalog is unchanged. These existing confirm: true summaries remain explicitly unconfirmed:

• GpsdOsmViewer: Android app showing gpsd positions on OpenStreetMap
• echo: TCP echo server and client demonstrating SNode.C socket contexts
• websocket-echo: WebSocket echo server, client and browser demo built on SNode.C
• tiktaktoe: Browser tic-tac-toe game with a SNode.C WebSocket subprotocol
• ServerClient: Interactive chat server and client built on SNode.C
• MiniGateway: Simulated measurement gateway with HTTP, server-sent events and MQTT
• INJA-Templatebuilder: Web interface for rendering Inja templates with JSON data through SNode.C
• IM510-Project: Course forum web application with users, topics, threads and posts
• snodec-forum-webapp: SNode.C forum web application with a MariaDB backend
• SnodeCWebForum: SNode.C web forum with users, topics, posts and comments
• simple-form-snodec: Vue frontend and SNode.C REST backend for a discussion forum
• IOTApplicationDesigner: Visual editor for IoT topics and mappings with import and export
• leiches-masterproject: HTTP and WebSocket backend and web frontend for Philips Hue control
• mqtt-open-hue: Headless C++ gateway connecting a Philips Hue Bridge with MQTT

Existing final accent pairs (unchanged)

Accent	Light text / background	Dark text / background
foundation-blue	#075985 / #e0f2fe	#7dd3fc / #082f49
iot-green	#166534 / #dcfce7	#86efac / #052e16
protocol-violet	#5b21b6 / #ede9fe	#c4b5fd / #2e1065
interface-amber	#92400e / #fef3c7	#fcd34d / #451a03
teal	#115e59 / #ccfbf1	#5eead4 / #042f2e
coral	#9f1239 / #ffe4e6	#fda4af / #4c0519
slate	#334155 / #f1f5f9	#cbd5e1 / #0f172a
neutral-grey	#374151 / #f3f4f6	#d1d5db / #111827

All eight existing accent pairs pass WCAG AA normal-text contrast (≥4.5:1) in both themes. Existing glyphs and tokens are unchanged.

Profile preview. No merge, workflow-tag move or version release is performed by this PR.

Review update: graphical menus and banner landing links

The four companion PRs restore the original blue-gray SVG block-button style at consistent 108×24 sizing, with link titles, image alt text, and collapsed plain-Markdown navigation. The same buttons/destinations appear in their docs indexes. Menu text contrast is 12.91:1 in both themes. Original menu assets apart from the approved back-arrow translations, and all banners, remain unchanged; the two existing product Build buttons are reused directly.

Organization Start-here, repository-table and dependency links to snode.c, mqttsuite, AISuite and CodexUI now point to their source-verified #project-overview banner anchors. Anchor evidence is kept in GitHub metadata, not guessed or put in the identity catalog. Workflow/release paths stay unfragmented; entries without a verified anchor retain their existing URLs. New regressions check these boundaries and URL-fragment encoding. No merge, tag move or manual CI dispatch occurs.

Review update: centred arrows and secondary buttons

The companion PRs now render 23 separate secondary destinations across 17 callouts as short arrow-ended buttons. Each original URL and full accessible label remains intact. The two existing back arrows move up exactly 1 px, without resizing; main-menu buttons without arrows and all banners remain untouched. The frame contract and preservation report document this approved update.

Verification: strict scoped-diff/content restoration, all 23 original link destinations and accessible labels, GitHub GFM rendering, desktop/mobile local Chrome previews in light/dark, main-menu geometry/contrast/fallback checks, 50 original fenced examples and 59 legacy anchors retained. Control catalog, 31 tests and deterministic profile drift pass. Browser previews use local CSS rather than claiming exact live GitHub appearance. Continuation production code: +0/-0; repository test code: +0/-0. Documentation/SVG assets only; no merge, tag change or manual workflow dispatch.

Final review decision: menu hierarchy and bold drawn arrows

Main-menu buttons stay arrow-free, at their existing 108×24 dimensions; they wrap naturally on narrow screens instead of being forced into a single oversized line. Secondary buttons use → and back buttons use ←. Ordinary text links remain unchanged.

All 21 arrow-bearing button assets now replace the thin font glyph with the same embedded filled SVG shape, mirrored for back navigation. It retains the original measured 9×4 ink bounds and centre y=12, with a bolder 1.5 px shaft. Button canvas, palette, titles, destination order and accessible labels remain unchanged; label positions agree within less than 0.016 px of SVG fractional positioning precision. There is no separate arrow file and no parallel font-arrow renderer. The 23-link / 17-callout “Go further:” conversion is already included.

Verified asset geometry and single-shape consistency, unchanged main-menu assets/README destinations, all preserved examples/anchors, catalog validation, 31 tests and profile drift, plus desktop/mobile local previews in both themes. Exact live GitHub CSS remains a user-browser review boundary. Continuation production source +0/-0; repository test source +0/-0. Only documentation and existing SVG assets change. No merge, tag move, package change or manual workflow dispatch.

Review correction: semantic symmetry without content loss

The editorial contract now fixes common link meanings and logical depth, not just label/order: Start is the short reader route, Install owns installation choices/requirements/steps, Build owns source compilation, Use owns first success/first run, Configure owns runtime settings, Architecture owns overview boundaries, and Contribute owns project reporting/contribution guidance. Existing API links remain direct references. All common entries first enter README-level sections, with topic-specific guides one level below; no new guide copy or production automation is introduced.

Preservation verification: all 50 original fenced examples remain byte-identical across the four repositories; every previously available anchor is retained; all original substantive non-routing prose, warnings, qualifications and licensing statements remain present. Only explicitly inventoried routing paragraphs were rewritten to separate responsibilities or update moved-command wording, preserving their choices, outcomes and caveats. Existing detailed guides, banners, figures and all SVG assets are byte-identical in this continuation. All local links/fragments, root/index button–Markdown parity, distinct semantic destinations and installation-command ownership pass checks. Catalog validation, all 31 control tests and profile drift pass; desktop/mobile local previews in light/dark inspected, not a claim of exact live GitHub CSS. Production source +0/-0; repository test source +0/-0; documentation only. No merge, workflow edit, package change, tag move or manual CI dispatch.

Latest review update: buttons-only navigation and installation redesign

• Remove the Text navigation dropdown and its duplicate links from all four root READMEs and docs indexes; linked buttons retain accessible labels, order and destinations.
• Rewrite Install as one Route / How to install table with only actual available routes. Remove duplicated package pitches, route rows and static platform enumeration; Packages remains the authoritative matrix.
• Align menu and Quick start roles: Install selects a route, Build compiles when needed, Use reaches a working result, Configure handles runtime settings/access controls. Quick start routes rather than repeats the installation procedure.
• MQTTSuite's service-exposure warning is rewritten as an application-by-application list under Configuration. Retain admin/admin, mutable mapping, disable/isolate advice and shared WebSocket/inspection-listener boundaries.
• Latest owner instruction: prose and link counts are not immutable; redundant passages and their links may be deleted. Examples, install commands, required prerequisites and material safety/availability qualifications remain.
• Documentation only: production source +0/-0; repository test source +0/-0. No CI, package pipeline, license file or tag changes. All existing guides, media and banners remain unchanged.
• Verified: all 31 control tests, catalog validation and profile drift; buttons-only/root-index parity, local links/fragments/images, installation boundaries and 50 unchanged fenced examples. Local light/dark mobile/desktop previews are not a claim of exact live GitHub CSS or product CI qualification.

Still open for review; not merged.

Organization menu correction

The six-area organization menu is now linked SVG buttons, matching the arrow-free 108×24 repository block menus. Visible labels: Framework, Suites, Applications, Learn, Community, Infrastructure. Full area labels remain accessible titles/alt text. No duplicate plain-link row or Text navigation dropdown. The renderer—not a hand-edit of generated Markdown—owns the replacement; area order/destinations still come from AREAS. Relative profile asset paths also work in branch previews.

Verified: six buttons in GitHub GFM output, existing heading targets and all assets; everything else in the generated profile is byte-identical; all 31 tests and profile drift pass. Production source +1/-1 (net zero), test source +24/-2. No consumers, CI, package pipeline or tags changed. Local mobile/desktop light/dark previews do not claim exact live GitHub CSS. Still open/unmerged.

Superseding installation-layout update: no tables

Replace the Install route tables in all four scoped READMEs with short, separate paragraphs and bold route labels. No grid, borders or panels. The common Install / Build / Use / Configure roles and button menus are unchanged. MQTTSuite's automatic framework-dependency note now belongs to the signed-package paragraph, not below the source route. The editorial contract is updated so the rejected table layout is no longer prescribed.

Documentation only: production source +0/-0, repository test source +0/-0. Verified no tables in rendered Install sections, route labels once each, all current links/anchors/assets, unchanged 50 fenced examples and all 31 control tests/profile drift. Existing guides, media, CI, packages, license files and tags remain unchanged. Still open for review; not merged.

Latest approved navigation: direct build guides; no long dash separators

• Keep Install as the concise route chooser; remove all four README Build from source sections.
• Build in root/index menus and source installation links go directly to the build guide. No README intermediary or dangling #build-from-source links.
• snode.c/mqttsuite use their existing docs/readme/install.md. AISuite/CodexUI move their full build prerequisites, configure/build commands and installation/prefix/privilege caveats into docs/build.md. CodexUI's native and browser routes share that guide; its web/README retains deployment/verification and links to the one source-build procedure rather than duplicating it.
• Install labels use bold colons (Signed packages:, From source:, Native desktop:, Browser frontend:), not long em dashes. Quick start adopts the same colon convention. Button assets, availability qualifications, runtime warnings and all first-use examples remain.
• The control editorial contract now reflects this approved exception: Build is a direct L2 guide entry, not a required README heading.

Verification: all 50 previous README fenced examples/commands retained byte-identically across their README and moved build guide; local files/fragments/images valid; normalized root/index/guide menus agree; no Install tables or long separators; all 31 control tests and profile drift pass. Layout checked with local GitHub-Markdown-style light/dark mobile/desktop previews, not exact live GitHub CSS or product build qualification.

Documentation only: production source +0/-0; repository test source +0/-0. No CI, packages, secrets, license files or tags changed. Not merged.