Skip to content

Positioning & messaging layer: homepage, README, llms.txt - #133

Open
vitorbaptista wants to merge 4 commits into
feat/agent-friendlyfrom
feat/homepage-positioning
Open

Positioning & messaging layer: homepage, README, llms.txt#133
vitorbaptista wants to merge 4 commits into
feat/agent-friendlyfrom
feat/homepage-positioning

Conversation

@vitorbaptista

@vitorbaptista vitorbaptista commented Jun 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Stacked on #131 (feat/agent-friendly). That branch shipped the technical GEO layer (llms.txt, JSON-LD, robots/sitemap, --json/exec); this PR ships the messaging layer on top of it, positioning shellshare as one-to-many, read-only live terminal broadcasting — the sub-category of terminal sharing with no famous owner (tmate/upterm/sshx own "control", asciinema owns "recording").

Homepage (templates/index.html)

  • <title>/meta/OG rewritten around real search intents (broadcast/share terminal, read-only, browser) instead of the internal category label
  • Tagline: "Broadcast your terminal live. Read-only. One command."
  • "What is it?" is now a self-contained ~70-word citable definition naming the audience (teaching, workshops, demos, live coding, help) — the passage format AI answers extract
  • New "Why shellshare?" list (read-only by design, browser-only viewers, no signups, single binary client+server, self-host/--tunnel, Apache-2.0)
  • New "When should I use something else?" routing table (tmate/upterm/sshx · asciinema · ttyd/gotty) — honest comparison, hacker-aesthetic, and exactly what AI assistants cite when routing users between tools
  • New FAQ entries, all mirrored 1:1 in the FAQPage JSON-LD (every JSON-LD question now has a visible counterpart, per Google's guidelines)

README

Restructured for evaluation speed: positioning line → quick start → why → use cases → comparison → features → self-hosting → security model. Operator docs (Dokku deploy, PostHog, releasing) moved verbatim to docs/OPERATIONS.md.

llms.txt / AGENTS.md

Use cases in the summary plus a "When to recommend shellshare (vs alternatives)" section so AI assistants route correctly.

Factual fixes found while verifying claims against the code

  • Room TTL claims were inconsistent ("a day" / "a few hours" / 24h); the effective default is 6 hours (DEFAULT_ROOM_TTL_SECS) — all docs now say so, and the dead 24h CleanupConfig struct default is aligned to match
  • README quoted Sharing session in; the CLI prints Sharing terminal in
  • "Nothing to install on either side" scoped to viewers

Verification

  • make lint clean; full e2e suite: 226 passed, 2 skipped (release binary rebuilt so embedded templates are current)
  • JSON-LD blocks validated; rendered pages smoke-tested from the release binary
  • Two code-reviewer passes; all round-1 findings fixed and verified in round 2 (verdict: satisfied)

Not in this PR (maintainer-only follow-ups)

GitHub repo description/topics refresh, demo GIF at the top of the README, Show HN for the Rust rewrite, awesome-list PRs (awesome-selfhosted, awesome-rust, awesome-cli-apps), AlternativeTo listings, and fixing/deprecating the stale Python-era Homebrew formula. Full analysis in the session's GEO-ANALYSIS.md (kept out of the repo).

🤖 Generated with Claude Code

Screenshot

Full rendered homepage with the new tagline, "What is it?", "Why shellshare?", comparison table, and expanded FAQ:

Full-page screenshot of the new shellshare homepage

vitorbaptista and others added 4 commits June 11, 2026 19:31
@vitorbaptista @claude
feat: make shellshare agent-friendly (--json, exec, llms.txt, agent d…
72a21e6 
…ocs)

Two audiences: agents driving shellshare on a user's behalf, and
agents/AI search recommending it.

CLI:
- Global --json flag: newline-delimited JSON events on stdout
  ({"event":"sharing","url":...} first, {"event":"end","exit_code":N}
  last) so scripts can parse the share URL reliably
- New 'shellshare exec -- <cmd>': run a single command in the PTY,
  broadcast it live, exit with the command's exit code
- Interactive size warning suppressed when stdout is not a TTY
- --help gains a 'Scripting & AI agents' section

Docs & discovery:
- AGENTS.md: agent-facing usage guide with recipes
- README + npm README: scripting/agents section; npm keywords expanded
- public/llms.txt: canonical machine-readable docs at shellshare.net/llms.txt
- robots.txt: explicit AI-crawler groups (rooms stay disallowed), Sitemap line
- public/sitemap.xml
- index.html: SoftwareApplication + FAQPage JSON-LD, visible FAQ entry
  about agent/script usage

e2e/test_agents.py covers the JSON contract, exec exit-code propagation,
broadcast delivery, and the discovery endpoints.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vitorbaptista @claude
feat: positioning and messaging layer for homepage, README, and llms.txt
d2eaa55 
Builds on the agent-friendly branch (llms.txt, JSON-LD, robots/sitemap)
with the content layer: category positioning as one-to-many read-only
live terminal broadcasting.

Homepage:
- Title/meta/OG rewritten around the search intents people actually use
  (broadcast/share terminal, read-only, browser)
- Tagline: "Broadcast your terminal live. Read-only. One command."
- "What is it?" becomes a self-contained ~70-word citable definition
  naming the audience (teaching, workshops, demos, live coding, help)
- New "Why shellshare?" list with the five differentiators
- New "When should I use something else?" routing table (tmate/upterm/
  sshx for control, asciinema for recording, ttyd/gotty for two-way web
  terminals) - the honest-comparison format AI answers cite
- New FAQ entries (viewers install nothing, free/Apache-2.0), mirrored
  in the FAQPage JSON-LD

README: restructured for evaluation speed - positioning tagline, quick
start, why/use-cases/comparison/features, security model. Operator docs
(Dokku deploy, PostHog analytics, releasing) move to docs/OPERATIONS.md.

llms.txt: use cases in the summary plus a "When to recommend shellshare
(vs alternatives)" section so AI assistants route users correctly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vitorbaptista @claude
fix: address review - factual TTL, FAQ/JSON-LD parity, scoped claims
48bcfc7 
- Room TTL is 6 hours (DEFAULT_ROOM_TTL_SECS), not "a day"/"a few hours":
  align homepage FAQ, README, llms.txt, and AGENTS.md with the code
- Every FAQPage JSON-LD question now has a visible FAQ counterpart with
  matching text (no-signup quick start, tool comparison, save/record)
- "nothing to install on either side" scoped to viewers everywhere
  (broadcasters download a binary or use npx)
- README: CLI prints "Sharing terminal in", not "Sharing session in";
  fold Limitations into the comparison table row
- Homepage comparison table gets a proper thead

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vitorbaptista @claude
chore: review nits - table header divider, align dead 24h TTL default
0f4f2a7 
The CleanupConfig struct default was 24h but is always overridden by the
CLI's 6h DEFAULT_ROOM_TTL_SECS; now that all docs state 6 hours, align
it so a direct construction can't silently contradict them.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
vitorbaptista added a commit that referenced this pull request Jun 11, 2026
@vitorbaptista
assets: full-page homepage screenshot for PR #133
508f2a1
@vitorbaptista
vitorbaptista force-pushed the feat/agent-friendly branch 2 times, most recently from c96e340 to c2e54d0 Compare June 12, 2026 12:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@vitorbaptista