feat: make Cockpit easy to find, install and give feedback on

[titan-ron]

What and why

Hardly anyone outside the team has tried Cockpit yet: 8 unique repo visitors in two weeks (all arriving from github.com), 6 disk-image downloads ever, and no issues from outside the team. The README had no picture, the first install ran into Gatekeeper, and there was no feedback path, from inside the app or on GitHub. This PR fixes those three things.

Find it

• The README now opens with a recorded hero, the three reasons to use Cockpit, a one-line install, what it sends where, and where feedback goes. The code map moves to CONTRIBUTING.
• The user guide in docs/ is published to GitHub Pages by docs.yml at https://tashtit.github.io/cockpit/ (base /cockpit/). It has no analytics, a sitemap, and a social card as its og:image. Pull requests only build it, which fails on a dead link.
• npm run ui:readme records the pictures from the ui-tour fixture world, so no real session, repo or account appears in them:
  • hero.gif — real frames from Chromium's own frame stream, 15 fps, 1.2 MB
  • chat, roundtable and search stills
  • the social card

Install it

• curl -fsSL https://raw.githubusercontent.com/tashtit/cockpit/main/scripts/install.sh | sh
  • curl sets no quarantine flag, so the app opens directly.
  • It checks the zip against the SHA-256 digest GitHub recorded, and checks the bundle id and version.
  • It swaps the new app in beside any installed copy and puts the old one back if anything fails.
  • It refuses to run while Cockpit is running, and --dry-run shows what it would do.
  • It never reads latest-mac.yml, so that file's download count keeps meaning "installed copies checking for updates".
• brew install --cask tashtit/tap/cockpit goes through the new tashtit/homebrew-tap. Its cask PR isn't open yet; see below.
• Getting started and the release-page template now lead with these two. The disk image and its Gatekeeper steps stay as the alternative.

Tell us

• Settings › About › Feedback: Report a problem, Sessions missing or wrong, Suggest an idea, Questions & discussion.
  • The two reports prefill the issue form with the Cockpit version, macOS version and architecture, and each agent CLI's version and install method. Nothing else goes in.
  • The CLI versions are read on the click, with a 4-second limit. AppInfo gains osVersion.
• Issue forms: bug, sessions (asks for the agent and CLI version, and asks people not to attach logs) and idea, plus a config.yml pointing to Discussions and private security reports.
• A PR template, and a Contributor Covenant code of conduct whose reporting path is GitHub's Report content.

Measure it

• npm run stats reports:
  • feedback from people outside the team
  • traffic
  • release downloads by meaning: disk images are new installs, zips are updates, latest-mac.yml fetches are update checks, which give an active-install range
• It keeps a local history past GitHub's 14-day window, with no telemetry.

How it was checked

• npm run typecheck: clean.
• npm test: 1,388 unit tests (1 skipped) and 470 component tests pass.
• npm run docs:build with the new base: pages, sitemap and og:image render under /cockpit/.
• npm run ui:tour: 100 shots, none missing. About was checked at desktop size, 900×700, the 560×420 floor and 200% zoom. The a11y and window-minimum e2e specs were run against the build.
• install.sh:
  • 10 tests drive the script the way the one-liner does (curl … | sh) against a local fake release: fresh install, upgrade, digest mismatch, missing digest, wrong bundle id, wrong version, a different app at the path, running app, dry run.
  • They're macOS-only, so CI's Linux unit tier skips them.
  • A dry run against the real latest release resolves both arches with their digests.
• npm run stats was run twice against this repo; the second run merged into the history instead of duplicating it.
• Seen in the running app (npm run dev).

After merge

• GitHub Pages must be enabled with GitHub Actions as its source, or the first deploy fails.
• The social preview has no API: upload docs/public/readme/social-preview.png under Settings › General › Social preview.
• The brew line works once the tap's cask lands.

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/unit

The overall line coverage in commit c72e772 in the titan/cockpit-user-f... branch remains at 79%, unchanged from commit f5b5d16 in the main branch.

Show a line coverage summary of the most impacted files.

File	main f5b5d16	titan/cockpit-user-f... c72e772	+/-
src/shared/feedback.ts	0%	100%	+100%

TypeScript / code-coverage/component

The overall line coverage in commit c72e772 in the titan/cockpit-user-f... branch remains at 88%, unchanged from commit f5b5d16 in the main branch.

Show a line coverage summary of the most impacted files.

File	main f5b5d16	titan/cockpit-user-f... c72e772	+/-
src/renderer/sr...boutSection.tsx	88%	90%	+2%

---

_{Updated September 24, 2026 15:38 UTC}