Skip to content

docs: community health files + README gaps#55

Merged
DocGerd merged 2 commits into
mainfrom
feat/10-community-health
Jul 17, 2026
Merged

docs: community health files + README gaps#55
DocGerd merged 2 commits into
mainfrom
feat/10-community-health

Conversation

@DocGerd

@DocGerd DocGerd commented Jul 17, 2026

Copy link
Copy Markdown
Owner

Closes #10

Summary

  • Adds SECURITY.md referencing GitHub private vulnerability reporting
    (enabled on the repo as part of this PR — private-vulnerability-reporting
    now reports enabled: true) and CONTRIBUTING.md covering ground rules,
    dev commands, the data pipeline, and the design-spec source of truth.
  • Adds a ## Screenshots section to README.md (start view + a planned
    Flensburg → Sønderborg route) and a ## Architecture section with a
    mermaid diagram of the pipeline → committed-assets → runtime data flow,
    plus a short timeout-policy note appended to the Development section.
  • Adds docs/screenshots/capture.mjs, a standalone Playwright script (not
    wired into CI) that drives the live app to (re)generate the two README
    screenshots on demand.

Deviations from the task brief

The brief's capture.mjs draft used selectors that don't match the current
app (verified against app/e2e/plan.spec.ts, HarborPicker.tsx, App.tsx,
RouteSummary.tsx before running anything, per repo convention):

  • The harbor search <input> has no placeholder — getByPlaceholder(/search harbor/i) never matches. Fixed to the e2e pattern: region-scoped
    getByRole('searchbox') inside getByRole('region', { name: 'Origin' | 'Destination' }).
  • Harbor result buttons are matched structurally (.harbor-picker li button, first result), not by name regex — a harbor's displayed name can
    differ from the search string by locale (e.g. Sønderborg displays as
    "Sonderburg" in German; see plan.spec.ts's comment on this).
  • The language-toggle button's accessible name is its aria-label
    ("English anzeigen" on first load), not its visible "EN" text — aria-label
    wins over text content in accessible-name computation, and unscoped "EN"
    string-matches several harbor names (Flensburg, Apenrade, ...) too.
  • RouteSummary (rig tabs, ★ recommendation, legs, totals) only mounts on
    the "Routes" tab (App.tsx: tab === 'routes'), not inline on "Plan" —
    the script switches tabs after planning before screenshotting.
  • NODE_PATH=app/node_modules (suggested as a fallback in the brief) does
    not work for this script: Node's ESM resolver, unlike CJS require,
    ignores NODE_PATH entirely. Since docs/screenshots/ has no ancestor
    node_modules containing @playwright/test, the script instead resolves
    it via an explicit relative file:// URL computed from import.meta.url
    (app/node_modules/@playwright/test/index.mjs), so node docs/screenshots/capture.mjs works standalone from the repo root with no
    extra env var.
  • The panel scrolls to wherever it last focus-landed after switching to the
    "Routes" tab (empirically, deep in the legs table) — the script now scrolls
    .app-panel back to the top before the final screenshot so the ★
    recommendation and route totals are actually visible in the captured image,
    not just the leg rows.

Both screenshots were regenerated against the live app with these fixes and
visually confirmed (map + harbor UI on the start view; a real rendered route
polyline, rig comparison with ★ recommendation, and per-leg table on the
route view) before committing.

Test plan

  • gh api repos/DocGerd/sail_command/private-vulnerability-reporting --jq .enabledtrue
  • npx markdownlint-cli2 README.md SECURITY.md CONTRIBUTING.md — 11
    advisory findings (no committed config), all pre-existing style patterns
    (long lines, bare URL, no first-line H1) or the same style applied to new
    content; nothing blocking.
  • docs/screenshots/start-view.png / plan-route.png regenerated via
    node docs/screenshots/capture.mjs against the live app and visually
    confirmed (322 KB / 382 KB, both well above the blank-capture threshold).
  • Eyeball mermaid + screenshot rendering on this PR's "Files changed"
    rich diff.

🤖 Generated with Claude Code

Comment thread README.md Outdated
@DocGerd
DocGerd merged commit 66edb9e into main Jul 17, 2026
2 checks passed
@DocGerd DocGerd mentioned this pull request Jul 17, 2026
7 tasks
@DocGerd
DocGerd deleted the feat/10-community-health branch July 17, 2026 14:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Public readiness: proper README + community health files

1 participant