docs: add an interactive plain-English tour of how Firstmate works - #2534
Open
MikeyB03 wants to merge 2 commits into
Open
docs: add an interactive plain-English tour of how Firstmate works#2534MikeyB03 wants to merge 2 commits into
MikeyB03 wants to merge 2 commits into
Conversation
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Intent
Create a comprehensive, plain-English interactive HTML explanation of the current Firstmate implementation at docs/how-firstmate-works.html, with a short tracked evidence note. Inspect and accurately trace material claims to current scripts, authoritative docs, tests, and hooks. Cover the mental model, component map, session start and supervision loop, task and Second Mate lifecycles, hooks and safety controls, durable state and recovery, captain-facing experience, worked scenarios, glossary, and FAQ. Include an at-a-glance system map, session and supervision sequence, task state machine, and filesystem and state hierarchy, with progressive disclosure, responsive keyboard-accessible print-friendly layout, no horizontal overflow, and sanitised examples containing no credentials, private messages, sensitive paths, or machine-specific details. Distinguish current behaviour, verified limitations, and proposed enhancements. Explain HMS Surprise display identities over mechanical task IDs; harness versus model versus backend versus Herdr Space; turn-end guard, heartbeat, wake, stale and open-decision semantics; durable authority versus notification history; no-mistakes versus direct-PR versus local-only with explicit merge authority; the current Codex no-supported-tool-row-filter limitation versus Pi Calm; and label a clean Captain View only as a future possibility. Keep tracked Markdown one sentence per physical line and use plain dashes. Validate local links, HTML, accessibility, desktop and narrow rendering, print behaviour, and repository documentation checks. Preserve the private Lavish review surface, never publish it, push only through no-mistakes, open a PR, drive CI green, and never merge. The existing README banner palette is the selected design source, Mermaid is used for the routed diagrams, and the completed decision inventory found no genuine unresolved captain choices.
What Changed
docs/how-firstmate-works.html, a self-contained interactive explainer of the current Firstmate implementation: mental model, component map, session start and supervision loop, task and Second Mate lifecycles, hooks and safety controls, durable state and recovery, captain-facing experience, worked scenarios, glossary, and FAQ, with Mermaid system-map, sequence, state-machine, and filesystem diagrams behind progressive-disclosure expanders.docs/how-firstmate-works-evidence.mdrecording the principal tracked sources behind the page's claims and the validation run against it (documentation-audience check, audience test, HTML/link/anchor audit, desktop and narrow browser rendering, keyboard and accessibility checks, print output).maintainer-verificationindocs/documentation-audiences.json.Risk Assessment
✅ Low: Fix round is a 3-line CSS/label change in one docs HTML file; both prior findings are correctly addressed and existing width, wrapping, and scroll-region safeguards cover overflow without the removed clamp.
Testing
Ran the repo's documentation-audience test and doc-audience checker (both pass), then drove the page in a real browser to gather visual evidence: desktop and 390px screenshots, all three diagram captures, the captain-view section showing the labelled Codex limitation and not-implemented Captain View, plus a printed A4 PDF with page images. Accessibility, keyboard, overflow, print, and link checks all pass; no failures or flakiness found.
Evidence: Print output (35 A4 pages)
Source: Print output (35 A4 pages)
Evidence: Lighthouse and geometry summary
Pipeline
Updates from git push no-mistakes
✅ **intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
docs/how-firstmate-works.html:39-overflow-x: hiddenon bothhtmlandbodyhides horizontal overflow instead of preventing it, so the evidence note's "no document-level horizontal overflow" check passes by construction and can never detect a genuinely too-wide child. It also makesbodya scroll container in browsers that resolveoverflow-y: visibletoauto, which can break the sticky topbar (line 116) and sticky sidebar (line 193). Prefer removing the clamp and relying on the existingmin-width: 0/overflow-wraprules plus the labelled.table-shellscroll regions.docs/how-firstmate-works.html:1651- The filesystem hierarchy nestsdata/,state/,config/, andprojects/under a node labelled "Firstmate code root/" described as tracked scripts and docs. Per docs/configuration.md:194-195 those are the operational home's directories and only coincide with the code root whenFM_HOMEis unset; the page itself distinguishes "Private operational home" at line 1148. Relabelling the root as the effective Firstmate home would keep the diagram accurate under a setFM_HOME.docs/how-firstmate-works.html:2052- Mermaid is loaded from a jsDelivr CDN, so the three routed diagrams degrade to raw source text when the page is opened offline or from an air-gapped checkout; the print path inherits the same dependency. Intent selected Mermaid, so this is an accepted tradeoff worth noting rather than a defect.🔧 Fix: drop overflow clamp and relabel filesystem tree root
1 info still open:
docs/how-firstmate-works-evidence.md:31- The evidence note's line "Browser geometry checks found no document-level horizontal overflow at either viewport" was recorded whilehtml/bodystill carriedoverflow-x: hidden; that clamp is now removed, so the geometry claim is no longer backed by a run against the current CSS. The remaining safeguards look sound (min-width: 0on layout containers,overflow-wrap: anywhereon text nodes,minmax(0, 1fr)tracks,.table-shell/.mermaid-wrapscroll regions,.tree-rowcollapsing to1frin the narrow media query), so this is a note to re-run the 1440x900 and 390x844 geometry check rather than a suspected defect.✅ **Test** - passed
✅ No issues found.
bash tests/fm-documentation-audiences.test.sh(4 checks pass)bash bin/fm-doc-audience-check.sh— ok surfaces=69 local_links=278Browser render ofdocs/how-firstmate-works.htmlover a local static server: 3 Mermaid SVGs with titles, 0 console errorsOverflow geometry check at 1440x900 and 390x844: documentElement.scrollWidth - clientWidth = 0; all 4 wide tables inrole="region"aria-labelledoverflow-x: autoshellsKeyboard: first Tab focuses.skip-link;Open technical evidenceopens 22/22details,Close expanderscloses allchrome-devtools-axi lighthouse— Accessibility 100, Best Practices 100, 58 audits passed, 0 failedHeadless Chrome--print-to-pdf+pdfinfo/pdftotext: 35 A4 pages, collapsed evidence text present, screen-only control labels absentLink audit script over the HTML: 69 unique hrefs, all local files and anchors resolve✅ **Document** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.