From 1e87354d7eaf5a31396d0d60f89ff722c5b343ba Mon Sep 17 00:00:00 2001 From: Vojtech <119944107+cvrysanek@users.noreply.github.com> Date: Wed, 13 May 2026 23:44:11 +0400 Subject: [PATCH] feat(home): Getting Started + Overview + Usage modes sections (release 0.54.7) (#291) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(home): Getting Started + Overview + Usage modes sections Three new content cards rendered between the install-hero and the existing connector tiles on /home. Order: Getting Started → Overview → Usage modes → connectors. - Getting Started — dismissible card with two clickable rows linking to /setup (install flow) and /setup-advanced (deeper reference). Subsumes the legacy `.advanced-pointer` row that sat above the news section. Per-device dismiss via a generic localStorage handler: `.home-card-close[data-dismiss-key="..."]` inside a
wires itself up at page load — drop in any future dismissible card without per-card JS. - Overview — operator-owned HTML body sourced from the new `instance.overview` yaml field (env override `AGNES_INSTANCE_OVERVIEW`). HTML in, HTML out via the same `| safe` filter as news_intro. Empty default hides the section entirely, keeping the OSS vendor-neutral; operators paste their product framing / privacy posture into instance.yaml. New helper `get_instance_overview()` in app/instance_config.py mirrors `get_instance_logo_svg()`. - Usage modes — three OSS-shipped tiles (Terminal / VS Code / Claude Desktop · claude.ai) explaining each surface and linking to the matching /setup-advanced anchors. Closes the gap for users wondering "where do I actually run this". Supporting changes: - setup_advanced.html gains a new `#claude-app` section between #vscode and #workspace, anchored by the Usage modes Claude Desktop tile. Covers the marketplace registration paths and when to prefer the terminal. Added to the table of contents. - Three new tests in test_web_home_page.py pin the Getting Started card markup, the Overview-on-when-yaml-set path, and the Overview-off-by-default path. All 13 tests in the file pass. Operator follow-up (separate infra PR — NOT this PR): paste the Foundry-specific Overview body into instance.yaml's `instance.overview` field. OSS ships with an empty default. * fix(home): Overview is operator-owned content — drop dismiss button Earlier iteration added a close X to the Overview section to match the Getting Started card's dismiss UX. Wrong call: Overview is operator-authored reference content (privacy posture, telemetry policy, project framing) and a per-device localStorage hide means returning users who want to re-read the policy can't recover it without clearing storage. Reverts the close button + the data-dismiss-key on the Overview section. Test inverted to assert the dismiss key is absent (defends against a future drive-by adding it back). Getting Started still dismisses — that's procedural getting-started content users legitimately stop needing once they've finished setup. Overview is always reachable; whole section is still opt-in at the operator level via the empty-yaml default. * fix(home): Terminal usage-mode tile is informational (no click-through) The setup hero above /home's Usage modes already walks the user through the Claude Code CLI install — the Terminal tile click-through to /setup just round-trips back to content the user already scrolled past. Switch Terminal to a non-anchor
and scope the hover affordance to a.home-usage-item so VS Code + Claude Desktop tiles keep their click-through (those legitimately deep-link into /setup-advanced anchors). * fix(home): point Usage modes guidance at ~/{workspace}/Projects/ subfolder The bundled plugin scopes the session-analysis loop and the central-catalog sync to ~//Projects/, not the workspace root itself — that convention already appears in the install hero's Step 4 manual-fallback note ('Don't create ~//Projects/ manually — the bundled plugin offers to set it up after install'). Usage modes' footer guidance now matches: 'create every project under ~//Projects/'. Also calls out that the session-analysis loop is scoped to that root so users understand why working outside the workspace dir is invisible to the platform. --- CHANGELOG.md | 29 +++ app/instance_config.py | 16 ++ app/web/router.py | 3 +- app/web/templates/home_not_onboarded.html | 266 +++++++++++++++++++++- app/web/templates/setup_advanced.html | 16 ++ config/instance.yaml.example | 8 + pyproject.toml | 2 +- tests/test_web_home_page.py | 70 ++++++ uv.lock | 2 +- 9 files changed, 401 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cb80d5b..7517ac1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,35 @@ CalVer image tags (`stable-YYYY.MM.N`, `dev-YYYY.MM.N`) are produced for every C ## [Unreleased] +## [0.54.7] — 2026-05-13 + +### Added + +- `instance.overview` yaml field (env override + `AGNES_INSTANCE_OVERVIEW`) — operator-authored HTML body rendered in + the new Overview section on `/home`. HTML in, HTML out via the same + `| safe` filter as `news_intro`. Empty default hides the section, + keeping the OSS vendor-neutral. +- `/home` Getting Started card — dismissible, two clickable rows + linking to `/setup` (install) and `/setup-advanced` (deeper + reference). Per-device dismiss via localStorage key + `agnes_home_gs_dismissed`. Generic `.home-card-close[data-dismiss-key]` + + `
` pattern — drop-in for any future dismissible card. +- `/home` Usage modes section — three OSS-shipped tiles (Terminal / + VS Code / Claude Desktop · claude.ai) explaining each surface and + linking to the relevant `/setup-advanced` anchors. +- `setup_advanced.html` `#claude-app` section anchored by the Usage + modes tile — covers the marketplace registration paths (git + smart-HTTP + ZIP fallback) and when to prefer the terminal anyway. + +### Changed + +- `/home` legacy `.advanced-pointer` row (the "Going deeper — + Advanced setup" link that sat above the news section) removed — + the same link now lives in the new Getting Started card. Supporting + `.advanced-pointer` CSS stays in place as dead style to keep the + diff focused. + ## [0.54.6] — 2026-05-13 ### Changed diff --git a/app/instance_config.py b/app/instance_config.py index 15bb39d..84aa9b8 100644 --- a/app/instance_config.py +++ b/app/instance_config.py @@ -295,6 +295,22 @@ def get_instance_logo_svg() -> str: return (raw or "").strip() +def get_instance_overview() -> str: + """Operator-authored Overview body rendered on ``/home``. Markdown is + NOT auto-converted — operators paste HTML (matches the existing + ``news_intro`` ``| safe`` filter). Empty default = section hidden, + keeping the OSS vendor-neutral when an instance ships without + operator-specific framing. + + Resolution: ``AGNES_INSTANCE_OVERVIEW`` env > ``instance.overview`` + YAML > ``""``. Mirrors :func:`get_instance_logo_svg`. + """ + raw = os.environ.get("AGNES_INSTANCE_OVERVIEW") + if raw is None: + raw = get_value("instance", "overview", default="") + return (raw or "").strip() + + def get_workspace_dir_name() -> str: """Filesystem-safe folder name for the analyst's local workspace (``~/``). Defaults to :func:`get_instance_brand` diff --git a/app/web/router.py b/app/web/router.py index 5cfa975..b31a11d 100644 --- a/app/web/router.py +++ b/app/web/router.py @@ -25,7 +25,7 @@ from app.instance_config import ( get_gws_oauth_credentials, get_home_automode_visibility, get_instance_admin_email, get_atlassian_base_url, get_instance_brand, get_workspace_dir_name, - get_instance_logo_svg, + get_instance_logo_svg, get_instance_overview, ) from app.web.connector_prompts import all_connector_prompts from src.repositories.sync_state import SyncStateRepository @@ -345,6 +345,7 @@ def _build_context( INSTANCE_SUBTITLE = get_instance_subtitle() INSTANCE_COPYRIGHT = "" LOGO_SVG = get_instance_logo_svg() + INSTANCE_OVERVIEW = get_instance_overview() TELEGRAM_BOT_USERNAME = os.environ.get("TELEGRAM_BOT_USERNAME", "") SSH_ALIAS = "data-analyst" SERVER_HOST = os.environ.get("SERVER_HOST", "") diff --git a/app/web/templates/home_not_onboarded.html b/app/web/templates/home_not_onboarded.html index 5be2c0b..654bb07 100644 --- a/app/web/templates/home_not_onboarded.html +++ b/app/web/templates/home_not_onboarded.html @@ -101,6 +101,155 @@ } .home-mock .install-hero .lead strong { font-weight: 600; } +/* ── Getting Started + Overview + Usage modes (added in PR #289) ─── + Three new content cards rendered between the install-hero and the + connector tiles. Getting Started + Usage modes ship in OSS; + Overview body comes from instance.overview yaml (operator-owned), + hidden when unset. Generic dismiss pattern: any element with + ` +
+

Getting Started

+

Two quick next steps to get the most out of {{ instance_brand }}.

+
+ + +
+ Setup {{ instance_brand }} in your Claude Code + One-time install: copies a setup script to your clipboard, paste into Claude Code, done in ~10 minutes. +
+ + + + +
+ Go deeper into your AI workspace + VS Code layout, recommended plugins, multi-model second opinions, custom skills + rules + hooks, project workflows. +
+ + +
+ + {# Overview section — operator-owned, opt-in. Body comes from the + `instance.overview` yaml field via get_instance_overview() + (`AGNES_INSTANCE_OVERVIEW` env override). Empty value hides the + whole section, keeping the OSS vendor-neutral. #} + {# Overview is operator-owned reference content, not per-user + chrome — no dismiss button on purpose. A one-time per-device + hide would mean returning users who wanted to re-read the + privacy posture / telemetry policy can't get back to it + without clearing localStorage. The whole section is opt-in at + the operator level (empty yaml → section absent), which is + the right axis of control. #} + {% if config.INSTANCE_OVERVIEW %} +
+

Overview

+
{{ config.INSTANCE_OVERVIEW | safe }}
+
+ {% endif %} + + {# Usage modes — Terminal / VS Code / Claude Desktop · claude.ai. + Generic OSS-shipped copy linking to /setup and to /setup-advanced + anchors. Helps onboarded users find the right surface once they + know which workflow fits them. #} +
+
+

Where you can use {{ instance_brand }}

+

Same workspace, three surfaces. Pick whichever fits your flow — all three share the same plugins, data access, and credentials.

+
+
+ {# Terminal tile is informational — the setup hero above already + walks through the Claude Code CLI install, so a click-through + here would round-trip back to content the user just scrolled + past. Rendered as a non-anchor div; hover/cursor styles only + apply to the anchor variants below. #} +
+ + Terminal + Default. Run claude from any project under ~/{{ workspace_dir }}. Lowest overhead, fastest feedback loop. +
+ + + VS Code + Split-terminal layout — conversation on one side, diffs and tool output on the other. See Go deeper for the recommended layout. + + + + Claude Desktop / claude.ai + Connect this {{ instance_brand }} instance's plugin marketplace to your Claude Desktop or claude.ai account — same plugins, no terminal required. + +
+

For the deepest integration, create every project under ~/{{ workspace_dir }}/Projects/ — existing or new. The bundled plugin keeps each project in sync with the central catalog automatically, and the session-analysis loop is scoped to that root.

+
+
@@ -1492,14 +1723,10 @@ Set-Location "$HOME\{{ workspace_dir }}" {% endif %}
- - 🛠️ -
- Going deeper — Advanced setup - VS Code split-terminal layout, recommended Claude Code plugins (with copy-able install commands), multi-model second opinions (Codex + Gemini), custom skills + rules + hooks, project workflows, plan tier guidance. -
- → - + {# Legacy `.advanced-pointer` row removed — same link now lives in + the Getting Started card at the top of /home. `.advanced-pointer` + CSS (~line 721) is harmless dead style; left in place to keep + this diff focused. #} {% if news_intro %}
@@ -1778,6 +2005,29 @@ Set-Location "$HOME\{{ workspace_dir }}" applyMinimize(nowOn); }); } + + // ── Generic dismiss-card handler ───────────────────────────────── + // Any `