**Origin:** maintainer request (2026-07-31). An **idea** for the backlog with maintainer decisions recorded below — not yet a committed, milestoned story. · **Rough size:** M ## The idea A comprehensive **user manual as a help page in the app** — the functionality described from the user's point of view (deliberately **excluding** everything under `/admin`), for users to read and consult: - **Feature reference** — each individual feature and how to use it: the logbook dashboard, trips, legs (weather, engine-free honest statistics), GPX import and the audit trail, ships, people, sharing, settings (data export, API tokens, mail preferences, language). - **Basic scenarios walked end to end** — creating a trip and filling it with data (legs, GPX tracks, crew, weather, charter); **how persons and accounts link** (address-book entry → email invitation → accepted link → "Shared with me" → revocation); **sharing a trip** both ways (crew shares vs. the public read-only link). - **Working with AI agents** — a user-facing section on connecting the app over MCP, with focus on **Claude and ChatGPT**: setup steps, what an agent can do (anything a human can), example prompts, and how to revoke access. ## What it builds on **Exists already:** - **The content brief is written** — README's opening paragraph is a complete user-level feature inventory, and the app's route table (`apps/web/src/app/router.tsx:48–109`) enumerates exactly the screens the manual must cover: logbook `/`, trips, legs + `/legs/:legId/audit`, ships, people, settings, `/invite/:token`, `/s/:token`. - **The AI-agent section has a source** — `docs/CONNECTORS.md` already holds the Claude and ChatGPT setup walkthroughs (Settings → Connectors → add `https://…/mcp` → magic-link login → consent) and the six MCP tools (`whoami`, `trip`, `ship`, `person`, `leg`, `track`). That doc is operator-facing (verification checklist, log greps); the help page would carry the end-user half. - **Sharing/linking semantics are settled and documented** — crew invitation links `people.user_id` to the owner's address-book entry; the linked user reads every trip of that owner they are crew on ("Shared with me"), never the charter, never a write; revocation from the person's form (README → ownership exception; #182 made invitations person-scoped). The public link is separate: redacted, revocable, off by default (#126, #137 open on its scope). - **Page precedents both ways** — public routes outside `AppShell` (`/s/:token`, the landing page #181) and authenticated content pages inside it. The landing page (the signed-out homepage) has the footer that will carry the link. - **i18n** — full en + cs catalogs (`apps/web/src/i18n/en.json`/`cs.json`, ~780 keys) with a parity test; every UI string ships in both languages. **Genuinely new:** - **Long-form prose content in the SPA** — per-language **HTML files** bundled as text and injected into the page (decision 2 below), not catalog keys. The content is repo-authored and build-bundled — no user input ever passes through the injection path — but the mechanism (e.g. Vite `?raw` imports + `dangerouslySetInnerHTML`) is a first for this codebase and should be one small, commented component. - **A standing maintenance coupling** — a manual that describes every feature means every story that changes user-facing behaviour now also touches the help page. The documentation policy gains a binding clause for this (decision 3 below). - **Instance-aware content** — the connector URL in the AI section can be rendered from the page's own origin, so every reader sees *their* instance's real `/mcp` URL instead of a placeholder. ## Sketch of an approach - A `/help` route, **public** — outside `RequireAuth`, in the `/s/:token` / landing style — accessible without sign-in and **linked from the homepage** (the landing page's footer/nav; the signed-in app can link it from the same shell spot). - **All on one page**, sectioned with **anchor links** (`/help#sharing`, `/help#ai-agents`) and a small table of contents at the top, so the app can deep-link contextually later. - Prose as **per-language HTML text files** (`help.en.html`, `help.cs.html` or similar), imported as raw text at build time and injected into the page shell; the shell owns the TOC, language switching, and Ship's Log styling. - **No screenshots** — text only (with the occasional inline illustration at most); prose survives cosmetic UI changes, images don't. - The three scenario walkthroughs as narratives, not screenshot-by-screenshot click paths. - AI-agents section: what MCP is in one user-facing sentence, Claude setup, ChatGPT setup (condensed from `docs/CONNECTORS.md`, minus the operator checklist), 3–4 example prompts ("log yesterday's leg from this GPX", "how many night hours did I sail this season?"), and revocation via Settings → API tokens. - `/admin` is deliberately absent; the admin's manual is `docs/OPERATIONS.md` and stays repo-side. - **In the same change, extend `docs/IMPLEMENTATION-GUIDE.md` → "Documentation policy"** with the binding clause: *any user-facing change is reflected in the help page (and the other affected docs) in the same commit* — an out-of-date manual is a bug like any other stale doc. ## Constraints check - **RSS / no headless browser / no tile server / no 2nd DB:** untouched — a static SPA route. - **No external origins:** all content bundled. - **MCP parity:** no new operations — pure frontend content; nothing for the parity test to see. - **TS strict / money / HSTS:** standard or N/A. ## Decisions (maintainer, 2026-07-31) 1. **Public, no sign-in** — `/help` is reachable signed-out and linked from the homepage. 2. **Prose as HTML text files** injected into the page — per language, bundled at build time. 3. **Documentation policy extended** — the implementation guide gains the binding "user-facing change ⇒ docs (incl. help page) updated in the same commit" guidance as part of this story. 4. **No screenshots.** 5. **One page, anchor links** for navigation. 6. **`docs/CONNECTORS.md` overlap is accepted** — the setup steps exist twice (repo doc for operators, help page for users); no restructuring. Each carries a cross-reference note naming the other as its counterpart to keep in sync. 7. **No parity gate for the en/cs HTML files** — no automated check; a comment/instruction at the top of each file says the two are translations of each other and change together. Review discipline does the rest. ## Related - **Existing issues:** #181 (landing page — public content-page precedent, footer link location), #126 (public trip page — public route shape), #182 (person-scoped invitations — the linking flow the manual must describe), #137 (open: public-share scope control — the sharing section must track its outcome), #149 (admin screen — explicitly out of the manual's scope). - **Docs:** `docs/CONNECTORS.md` (AI-agent setup source), `docs/DESIGN.md` (voice), README opening paragraph (feature inventory), `docs/IMPLEMENTATION-GUIDE.md` → "Documentation policy" (gains the binding clause). --- *Filed at the maintainer's request; analysis by an AI agent from the docs + codebase; scope decisions recorded above are the maintainer's (2026-07-31).*