Docs-Sync #88: doc surfaces need updating when adaptive-sizing lands

[Sev7eNup]

Source PR: #88 — "Size the engine from detected hardware unless manual tuning is on" (status: open)

Summary

PR #88 introduces adaptive performance sizing: a new Performance:ManualTuning config key (default false) that switches between hardware-derived auto-sizing and the configured static values. It also adds a new GET /api/admin/settings/effective-sizing endpoint and changes the semantics of the existing appsettings.json performance values (they become an inert preset rather than actual effective defaults).

PR #88 already updates docs/performance-improvements.md and docs/claude-reference.md as part of the PR itself — those doc changes will land when the PR merges. However, several doc surfaces need human review on merge, and one stale claim in the existing docs may need coordination.

Affected doc surfaces

• docs/performance-improvements.md — "Aktueller Stand" section (lines 11–26) lists the static values from appsettings.json as the live configuration. Once PR Size the engine from detected hardware unless manual tuning is on #88 lands, these numbers become an inert manual preset (only active when Performance:ManualTuning=true); the section heading and framing need a one-line caveat so readers aren't misled.
• docs/claude-reference.md — needs entries for:
  • New config key Performance:ManualTuning (default false; hot-reload status to confirm)
  • New endpoint GET /api/admin/settings/effective-sizing (returns the plan in force and which constraint produced each value)
• CLAUDE.md tech-stack section — currently describes the engine sizing as static config values. If PR Size the engine from detected hardware unless manual tuning is on #88 makes auto-sizing the boot default, this framing may need a sentence about Performance:ManualTuning.

Why not auto-applied

• PR Size the engine from detected hardware unless manual tuning is on #88 is not yet merged — none of the new keys, endpoint, or semantic changes are on main yet. Editing docs for not-yet-landed code would get ahead of main, which this watchdog must not do.
• The framing changes in docs/performance-improvements.md require a judgment call about how to present "these values are now inert presets unless ManualTuning=true" without invalidating the tuning history documented there.

Checklist

• docs/performance-improvements.md "Aktueller Stand" section — add a caveat that the listed values are the manual preset (active only when Performance:ManualTuning=true); describe what the auto-sizing default produces instead, or link to the new GET /api/admin/settings/effective-sizing output.
• docs/claude-reference.md — add Performance:ManualTuning to the config-key reference; add GET /api/admin/settings/effective-sizing to the admin endpoint list.
• CLAUDE.md tech-stack section — verify the static sizing description is still accurate after the semantic change, or add a note about the ManualTuning switch.
• Verify PR Size the engine from detected hardware unless manual tuning is on #88's own doc changes (already in the PR diff) are complete and consistent once it lands — a follow-up sync run will catch residual drift, but this checklist is a heads-up.

Note: the "~30 MB per runspace" stale claim that PR #88 also intended to correct has already been fixed in this repo's docs by the nightly sync run of 2026-07-31 (PR #90), based on measurement data from the merged PR #87. No action needed on that item when PR #88 lands.

---

Automated docs-drift finding from nightly docs-sync run 2026-07-31T03:08 UTC. Needs triage.

[Sev7eNup]

Follow-up from nightly docs-sync run 2026-08-01T03:07 UTC — PR #88 has now merged. Updating this issue.

What PR #88's own changes resolved

• docs/claude-reference.md ✅ — Performance:ManualTuning and GET /api/admin/settings/effective-sizing are documented (confirmed on main, line 577).
• CLAUDE.md ✅ — "Dimensionierung" paragraph now covers PerformancePlanFactory, Performance:ManualTuning default false, and the excluded Engine:MaxConcurrentExecutions:* cap.
• docs/performance-improvements.md ✅ — "Hardware-adaptive Dimensionierung (Session 2026-07-31)" section added with formulas, memory-budget model, and ceilings. The tuning table already carries a caveat that its values are Performance:ManualTuning: true overrides (line 302).

What was auto-fixed in this sync run

• src/nodepilot-docs-ui/content/api/endpoints.md — GET /api/admin/settings/effective-sizing added to the Settings row in the docs-site endpoint table → PR docs: sync after #88 (add effective-sizing to docs-site API table) #93.

Two remaining items that need a human decision

• docs/performance-improvements.md "Aktueller Stand" section (lines 7–38) — The section header still says "Single source of truth für die Live-Konfiguration" and the block is labelled "Live in appsettings.json". With Performance:ManualTuning: false (the default after PR Size the engine from detected hardware unless manual tuning is on #88), those values are not the live configuration — they are an inert preset; PerformancePlanFactory computes the actual effective values from detected hardware. The tuning table below already carries the right caveat (line 302), but the header section does not. A one-line disambiguation is needed, e.g. marking the block as the "manual-tuning preset" and pointing to GET /api/admin/settings/effective-sizing for actual effective values. Exact wording is a judgment call — not auto-applied.

• src/nodepilot-docs-ui/content/configuration/appsettings.md — The docs-site configuration overview has sections for Cluster/HA, AI, Observability, Retention, and Hardening, each with a one-liner and a Details link. Performance:ManualTuning (default false, restart-required) is a comparably significant user-facing config switch but has no entry here. There is also no performance-specific page in the docs-site to link to (src/nodepilot-docs-ui/content/configuration/ has no performance.md). A human needs to decide: (a) add a ## Performance section with a brief description and either a link to docs/performance-improvements.md or create a new docs-site performance page; or (b) defer until a full performance config page is written. Not auto-applied: requires a decision on page structure.

---

Automated docs-drift follow-up from nightly docs-sync run 2026-08-01T03:07 UTC.

---

Generated by Claude Code