docs: S30.01 getting-started doc + integration manifest

[DavidCozens]

Purpose

First story of E30 (#566, frictionless integration). Authors the
getting-started front door + a hand-authored integration manifest so a
non-CMake integrator (the beta: FreeRTOS + lwIP + Mbed TLS + FatFs, IAR) can
build from docs alone. Docs only, authored against the current tree — zero CI
risk. (S30.03 later replaces the hand-authored manifest with a generated one.)

Closes #567

Change Description

• New docs/getting-started.md — the integrator front door:
  • "How SolidSyslog composes" (Core + adapters + your callbacks; Null fallback per role).
  • Capability matrix from E30: Frictionless integration — one-line-per-platform consumption + getting-started #566, trimmed to integrator-facing columns
    (provider / files / upstream dep / config / pool tunable), split into
    Networking / TLS+at-rest / OS+storage+SD / BYO-callback tables.
  • Two paths: Path A (CMake) is the current env-var/auto-detect path with a
    note that S30.02 makes it one-line; Path B (non-CMake) is the
    file/include/-D manifest, with the include-path rule made explicit.
  • Worked beta manifest — copy-pasteable Core + lwIP (numeric, DNS omitted
    so no LWIP_DNS) + Mbed TLS + FreeRTOS + FatFs .c lists, include dirs, the
    single required -D, the five integrator-owned config headers, and BYO callbacks.
  • Tunables section (uniform for both paths) and a minimal "your first log" walkthrough.
• docs/builds.md reframed as the contributor/maintainer preset catalogue;
  added the previously-missing c99, iwyu (documented accurately as
  advisory per S24.13 — not "dropped"), and freertos-cross-lwip presets.
• README cross-links getting-started as the integrator front door.
• DEVLOG.md updated.

Note on the handoff: the epic/story said to "remove stale IWYU references
(IWYU was dropped)". In fact builds.md had zero IWYU references and the
analyze-iwyu* lanes still run as advisory checks, so IWYU is documented as
advisory rather than removed.

Test Evidence

Docs only — no code, no tests, no build files touched (git diff --stat:
DEVLOG.md, README.md, docs/builds.md, docs/getting-started.md). Manifest
facts verified against the tree: Core is platform-clean (no platform/upstream
includes), the listed adapter .c groups and include-path requirements exist,
and the freertos-cross-lwip target/ELF names match CMakePresets.json +
Bdd/Targets/FreeRtosLwip/CMakeLists.txt.

Areas Affected

Documentation only (docs/, README.md, DEVLOG.md). No required CI check is
affected; no library, platform, or build target changed.

Summary by CodeRabbit

• Documentation
  • Added comprehensive getting-started guide covering integration paths, stack composition, capability matrix, tunables, and a first-log walkthrough.
  • Added new build documentation lanes: C99 baseline enforcement, IWYU advisory guidance, and FreeRTOS cross-build configuration with lwIP example.
  • Updated README to direct users to new getting-started guide for consuming the library.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR establishes integrator-facing documentation for consuming SolidSyslog. It introduces a new docs/getting-started.md guide with stack composition, a capability matrix, two integration paths (CMake and non-CMake manifest), a complete worked FreeRTOS+lwIP+MbedTLS+FatFs example, and usage patterns. Related updates clarify docs/builds.md as contributor-focused, cross-link from README, and document S30.01 completion.

Changes

Integrator-facing Getting-Started Guide

Layer / File(s)	Summary
Stack composition model and capability matrix docs/getting-started.md	Introduces the Core + adapters + callbacks/config composition model; documents the capability matrix mapping roles (networking, TLS, storage, OS, structured data) to providers, upstream dependencies, and pool tunables; specifies bring-your-own callback requirements (clock, uptime, sleep, hostname, atomic counter).
Integration paths and worked manifest docs/getting-started.md	Documents CMake consumer path (role selection via environment variables) and non-CMake manifest path (source files, include directories, compile-time defines). Provides a complete worked FreeRTOS+lwIP+MbedTLS+FatFs manifest with Core and adapter source lists, required include directories, tunables overrides, config headers, and callback wiring.
Tunables and first-log usage docs/getting-started.md	Explains compile-time tunables override mechanisms via -D flags or full header file. Shows end-to-end API usage: SolidSyslogConfig setup, SolidSyslog_Create, SolidSyslog_Log, SolidSyslog_Service drain, and SolidSyslog_Destroy teardown, including PassthroughBuffer vs CircularBuffer behavior and structured-data logging patterns.
Build documentation and cross-linking docs/builds.md, README.md, DEVLOG.md	Reframes docs/builds.md as contributor/maintainer-focused and redirects integrators to getting-started. Documents new CMake presets: c99 (C99 baseline), iwyu (advisory static analysis, not a CI gate), and freertos-cross-lwip (cross-build variant). Updates README with "Getting started" section and clarified "Building and testing" navigation. Records S30.01 completion and deferred work in DEVLOG.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• DavidCozens/solid-syslog#566: Parent epic defining the stack composition model, capability matrix, and beta worked example that are now documented in this PR's getting-started guide.
• DavidCozens/solid-syslog#567: This PR directly fulfills the S30.01 story objectives: authoring the getting-started front door, non-CMake manifest, worked beta example, and builds.md/README/DEVLOG updates.

Possibly related PRs

• DavidCozens/solid-syslog#469: Related documentation alignment on IWYU being advisory and non-blocking in the builds documentation.

Poem

📖 A rabbit hops through docs with glee,
Getting started, clear as can be!
The manifest paths, both CMake and bare,
First logs and tunables, all laid out fair. 🐰
From Core to adapters, the journey is planned,
Integration in hand, integrators stand!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change as adding getting-started documentation and integration manifest, directly summarizing the primary deliverable.
Description check	✅ Passed	The PR description follows the template with complete Purpose, Change Description, Test Evidence, and Areas Affected sections, providing detailed context and rationale.
Linked Issues check	✅ Passed	The PR fully addresses all requirements from #567: getting-started front door, capability matrix, two integration paths (CMake/non-CMake), worked manifest, tunables section, reframed builds.md, README cross-links, and DEVLOG update, with docs-only scope preserved.
Out of Scope Changes check	✅ Passed	All changes are scoped to documentation files (docs/, README.md, DEVLOG.md) with zero impact on code, build files, or CI, matching the issue's requirement of docs-only delivery.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/s30-01-getting-started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

☀️   Quality Summary

   🚦   build-linux-gcc: 100% successful (✔️ 1521 passed)
   🚦   build-freertos-host-tdd-plustcp: 100% successful (✔️ 1872 passed)
   🚦   build-linux-clang: 100% successful (✔️ 1453 passed)
   🚦   sanitize-linux-gcc: 100% successful (✔️ 1453 passed)
   🚦   integration-linux-openssl: 100% successful (✔️ 16 passed)
   🚦   integration-linux-mbedtls: 100% successful (✔️ 14 passed)
   🚦   integration-windows-openssl: 100% successful (✔️ 16 passed)
   🚦   bdd-linux-syslog-ng: 94% successful (✔️ 49 passed, 🙈 3 skipped)
   🚦   bdd-windows-otel: 88% successful (✔️ 46 passed, 🙈 6 skipped)
   🚦   bdd-freertos-qemu-plustcp: 87% successful (✔️ 45 passed, 🙈 7 skipped)
   🚦   bdd-freertos-qemu-lwip: 87% successful (✔️ 45 passed, 🙈 7 skipped)
   🚦   build-windows-msvc: 100% successful (✔️ 1298 passed)
   🚦   build-linux-tunable-override: 100% successful (✔️ 1453 passed)
   ⚠️   Clang-Tidy: No warnings
   ⚠️   CPPCheck: No warnings

---

Created by Quality Monitor v1.14.0 (#f3859fd). More details are shown in the GitHub Checks Result.

[coderabbitai]

🧹 Nitpick comments (3)

docs/getting-started.md (3)

176-178: ⚡ Quick win

Specify language for fenced code block.

Add a language identifier (e.g., text or sh) to improve syntax highlighting and satisfy markdownlint (MD040). This applies to all file-list code blocks in the manifest section (Lines 176, 190, 207, 217, 225, 236, 256).

📝 Example fix for Line 176

-```
+```text
 Core/Source/*.c

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @docs/getting-started.md around lines 176 - 178, Add a language identifier to
each fenced code block in the manifest section of docs/getting-started.md (the
file-list blocks like the one containing "Core/Source/.c") so markdownlint
MD040 is satisfied; update each triple-backtick block (e.g., the blocks showing
file globs such as "Core/Source/.c", and the other listed blocks at the
manifest section) to use a language token like text or sh before the file
list and keep the content unchanged.

</details>

<!-- cr-comment:v1:e2b372ba40640ae68e54a2b7 -->

---

`157-163`: _⚡ Quick win_

**Remove blank line inside blockquote.**

The blank line at Line 161 (between the two blockquote paragraphs) triggers a markdownlint warning (MD028). Markdown renderers may treat this as two separate blockquotes.




<details>
<summary>📝 Proposed fix</summary>

```diff
 > **Tip — adapter file groups.** For an adapter named `Foo`, compile every
 > `Platform/<X>/Source/SolidSyslogFoo*.c` (the `Foo` + `FooStatic` pair) and put
 > `Platform/<X>/Source` on the include path for the `FooPrivate.h` header.
 > The matrix above lists which groups you need per role.
-
+>
 > *(This manifest is hand-authored against the current tree. S30.03 will
 > generate it from CMake so it can never drift — see `#569`.)*
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/getting-started.md` around lines 157 - 163, Remove the stray blank line
inside the blockquote that splits the two paragraphs ("Tip — adapter file
groups." and the parenthetical about S30.03) so they are one continuous
blockquote; edit the block containing "Tip — adapter file groups." and the
subsequent parenthetical "(This manifest is hand-authored against the current
tree. S30.03 will generate it from CMake so it can never drift — see `#569`.)" and
delete the empty line between them to satisfy MD028.
```

</details>

<!-- cr-comment:v1:41b86ebb3ab0fb4dbab3389c -->

---

`34-40`: _⚡ Quick win_

**Inconsistent hyphenation of "prebuilt".**

Line 34 uses "prebuilt" while Line 40 uses "pre-build". Choose one form and use it consistently throughout the document.

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/getting-started.md` around lines 34 - 40, The document uses inconsistent
hyphenation for "prebuilt"—it appears as "prebuilt" in the phrase "Core is a
prebuilt `.a`" and as "pre-build" in "one-size pre-build."; pick one form
(prefer "prebuilt"), replace the other occurrence so both read the same, and run
a quick search through the doc to normalize any other instances to the chosen
spelling.
```

</details>

<!-- cr-comment:v1:3428b0c75238ea292d412dc0 -->

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In @docs/getting-started.md:

• Around line 176-178: Add a language identifier to each fenced code block in
  the manifest section of docs/getting-started.md (the file-list blocks like the
  one containing "Core/Source/.c") so markdownlint MD040 is satisfied; update
  each triple-backtick block (e.g., the blocks showing file globs such as
  "Core/Source/.c", and the other listed blocks at the manifest section) to use a
  language token like text or sh before the file list and keep the content
  unchanged.
• Around line 157-163: Remove the stray blank line inside the blockquote that
  splits the two paragraphs ("Tip — adapter file groups." and the parenthetical
  about S30.03) so they are one continuous blockquote; edit the block containing
  "Tip — adapter file groups." and the subsequent parenthetical "(This manifest is
  hand-authored against the current tree. S30.03 will generate it from CMake so it
  can never drift — see #569.)" and delete the empty line between them to satisfy
  MD028.
• Around line 34-40: The document uses inconsistent hyphenation for
  "prebuilt"—it appears as "prebuilt" in the phrase "Core is a prebuilt .a" and
  as "pre-build" in "one-size pre-build."; pick one form (prefer "prebuilt"),
  replace the other occurrence so both read the same, and run a quick search
  through the doc to normalize any other instances to the chosen spelling.

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: defaults

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `01372732-7037-466f-963b-e529ab7443e5`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 16ddce42536ed0b795e9ba2fd4849b76d2650b99 and 7be4a1923f1e688f631793d579472893cf48cdbe.

</details>

<details>
<summary>📒 Files selected for processing (4)</summary>

* `DEVLOG.md`
* `README.md`
* `docs/builds.md`
* `docs/getting-started.md`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->