mirror of
https://github.com/open-jarvis/OpenJarvis.git
synced 2026-07-28 05:12:26 +00:00
68b27654a8
Addresses feedback from our Discord admin curating #config-showcase: the
existing docs land non-technical users straight into Tutorials, which
are script-first and TOML-heavy ("standalone script you can run
immediately, a TOML recipe, a detailed walkthrough"). For a curious-
but-non-technical reader trying to decide whether OpenJarvis is worth
their weekend, that's the wrong first contact — they bounce before they
ever see what the framework can do for them.
This PR inserts a new Showcase tier *above* Tutorials in the docs
information architecture. Each entry is outcome-first: hook sentence,
hero screenshot, 2-3 short paragraphs of personal context, then a
"How I set this up →" link that lands on the relevant Tutorial /
User Guide. The Showcase is the funnel; Tutorials are the build steps.
Five inaugural entries — drafted to be paste-ready for #config-showcase:
- showcase/morning-brief.md — Slack/email/GitHub overnight digest
- showcase/persistent-memory.md — SOUL.md/MEMORY.md/USER.md story
- showcase/cost-savings.md — the public leaderboard as motivation
- showcase/discord-companion.md — DM Jarvis from anywhere
- showcase/coding-assistant.md — code review on an airplane
Plus the contributor template and an assets directory:
- showcase/CONTRIBUTING.md — format skeleton + editorial conventions
(screenshot specs, what to redact, tone)
- assets/showcase/README.md — asset directory conventions
- assets/showcase/*.png — placeholder hero screenshots (1600x1000,
6 KB each, dark gradient) so the gallery
renders cleanly before community
submissions populate real screenshots
Information-architecture changes:
- mkdocs.yml — insert "Showcase" tier between Getting Started and
Tutorials. Funnel order is now: land → "what's possible?" → "build it."
- docs/index.md — new hero card directly under the tagline, pointing to
the Showcase. The research-framework framing stays, but no longer
occupies the first scroll-fold.
CSS:
- docs/stylesheets/extra.css — `.showcase-screenshot` class adds rounded
corners + subtle border so hero images (placeholder or real) read as
intentional rather than as broken-image artifacts.
Validation:
- `uv run mkdocs build` (CI mode) succeeds.
- `uv run mkdocs build --strict` produces zero showcase-specific
warnings. The 18 remaining strict-mode warnings are all pre-existing
on main (`desktop-auto-update.md`, `telemetry.md`, griffe parser
warnings on existing source, mkdocs_autorefs cross-reference issues).
Explicit non-goals (deferred to follow-up PRs in the showcase-tier
roadmap):
- `jarvis showcase` CLI for personal recaps (PR #2)
- Showcase-aligned recipes in `src/openjarvis/recipes/data/` so
"How I set this up →" links into 2-command installs (PR #2)
- Automated screenshot regeneration via Playwright on release tags (PR #3)
- Replacing placeholder PNGs with real screenshots — that happens
organically as community contributors and team members submit their
own setups (see CONTRIBUTING.md for the format)
Co-authored-by: krypticmouse <herumbshandilya123@gmail.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Showcase screenshots
This directory holds the hero screenshot for each Showcase entry in docs/showcase/. Convention is one file per entry, named to match the entry's slug:
| Entry | Screenshot path |
|---|---|
docs/showcase/morning-brief.md |
morning-brief.png |
docs/showcase/persistent-memory.md |
persistent-memory.png |
docs/showcase/cost-savings.md |
cost-savings.png |
docs/showcase/discord-companion.md |
discord-companion.png |
docs/showcase/coding-assistant.md |
coding-assistant.png |
Conventions
| Format | PNG, sRGB, no alpha channel |
| Size | 1600×1000 (4:2.5 — wider than 16:9, so screenshots don't get letterboxed in the docs grid) |
| File size | Under 400 KB after pngquant --quality 70-90 --speed 1 |
| Loading | All <img> and <figure> tags in showcase pages use loading=lazy — these images are below the fold on the gallery page |
What to redact
- Real email addresses
- API keys, OAuth tokens, anything starting with
sk-,ghp_,xox,eyJ - Personal phone numbers
- Conversation partners' faces or full names (unless they've signed off)
- File paths that include other people's home directories
What to keep
- Model names ("llama3.1:8b", "qwen2.5:14b") — they're informative
- Timestamps — proves the screenshot is recent
- Dollar amounts on the leaderboard — the whole point
- Emoji reactions, your own first name, your own avatar
Placeholder PNGs
This directory ships with no images on the initial PR. The Showcase pages reference image paths that don't exist yet — MkDocs will render a broken-image placeholder, and the figcaption still conveys what should be there. Real screenshots arrive in follow-up PRs as Showcase entries are populated with each contributor's actual setup.
If you're contributing the first real entry, drop your PNG at docs/assets/showcase/<your-slug>.png in the same PR that adds your markdown page. The image filename must match the slug used in the showcase page's <img> reference.
Regenerating screenshots in bulk
A future enhancement (tracked as PR #3 in the showcase-tier roadmap) will add scripts/showcase/regen_screenshots.py — a Playwright-driven pipeline that boots a demo jarvis serve against a sealed config and captures fresh screenshots for every showcase entry on each release tag. Until that lands, screenshots are contributed manually by each Showcase author.