feat(webapp): strengthen public landing experience

Author: FelixTJDietrich

.changeset/calm-mentors-welcome.md

@@ -0,0 +1,5 @@
+---
+"hephaestus": patch
+---
+
+Clarifies how Hephaestus connects practice feedback and conversations with Heph to project work, and adds institutional attribution to the public pages.

.github/actions/setup-caches/action.yml

@@ -1,5 +1,5 @@
 name: "Setup CI caches"
-description: "Caches Maven repo + generated sources, Playwright browsers, and Storybook builds. Node/pnpm setup happens in the calling workflow via pnpm/action-setup + actions/setup-node (cache: pnpm)."
+description: "Caches Maven dependencies and Playwright browsers. Node/pnpm setup happens in the calling workflow."
 inputs:
   cache-type:
     description: "Type of cache to setup"
@@ -43,14 +43,3 @@ runs:
         key: ${{ inputs.os }}-playwright-${{ hashFiles('pnpm-lock.yaml') }}
         restore-keys: |
           ${{ inputs.os }}-playwright-
-
-    - name: Cache Storybook build
-      if: contains(fromJSON('["webapp-visual", "webapp-storybook"]'), inputs.cache-type)
-      uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-      with:
-        path: |
-          webapp/storybook-static
-          webapp/.storybook/.cache
-        key: ${{ inputs.os }}-storybook-${{ hashFiles('webapp/**/*.stories.tsx', 'webapp/.storybook/**', 'pnpm-lock.yaml') }}
-        restore-keys: |
-          ${{ inputs.os }}-storybook-

.github/workflows/ci-tests.yml

@@ -8,7 +8,6 @@ on:
         required: false
         type: string
         default: "false"
-      # Path-based change detection for selective test execution
       webapp_changed:
         description: "Whether webapp files changed"
         required: false
@@ -63,7 +62,6 @@ jobs:
               echo "run=${{ inputs.application_server_changed }}" >> $GITHUB_OUTPUT
               ;;
             *)
-              # Unknown test type - fail explicitly to catch missing case statements
               echo "::error::Unknown test type '${{ matrix.test-type }}' in ci-tests.yml matrix."
               echo "::error::Please add a case for this test type in the 'Determine if test should run' step."
               echo "run=false" >> $GITHUB_OUTPUT
@@ -116,7 +114,6 @@ jobs:
 
           case "${{ matrix.test-type }}" in
             "webapp-storybook")
-              # Install Playwright browsers (cached in ~/.cache/ms-playwright by setup-caches)
               pnpm exec playwright install chromium --with-deps
               # Bound browser-runner deadlocks without coupling CI to the current suite duration.
               timeout --kill-after=30s 15m pnpm run test:storybook
@@ -174,7 +171,6 @@ jobs:
           if-no-files-found: ignore
           retention-days: 14
 
-      # Chromatic visual testing
       - name: "Chromatic Visual Testing"
         if: >-
           steps.should_run.outputs.run == 'true' && matrix.test-type == 'webapp-storybook' && always() &&
@@ -211,7 +207,6 @@ jobs:
               context: 'Preview / Storybook'
             });
 
-      # Test result aggregation
       - name: Upload application-server test results
         if: steps.should_run.outputs.run == 'true' && always() && startsWith(matrix.test-type, 'application-server-')
         uses: dorny/test-reporter@a43b3a5f7366b97d083190328d2c652e1a8b6aa2 # v3.0.0
@@ -261,14 +256,12 @@ jobs:
             exit 1
           fi
 
-      # Test Summary for Job Summary
       - name: Generate test summary
         if: steps.should_run.outputs.run == 'true' && always()
         run: |
           echo "### 🧪 ${{ matrix.test-type }}" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
 
-          # Find and summarize JUnit XML results
           case "${{ matrix.test-type }}" in
             application-server-*)
               if [ -d "server/target/surefire-reports" ]; then

README.md

@@ -6,7 +6,7 @@
   </picture>
 
   <h1>Hephaestus</h1>
-  <p><strong>Feedback on how you work</strong></p>
+  <p><strong>Learn from the work you're already doing</strong></p>
 
   <p>
     <a href="https://hephaestus.aet.cit.tum.de"><img alt="Open the TUM-operated Hephaestus web app" src="https://img.shields.io/badge/web_app-open-493C83"></a>
@@ -21,65 +21,49 @@
   </p>
 </div>
 
-Hephaestus gives developers feedback on the engineering practices they use in software projects. It draws on evidence from tools the team already uses — including GitHub or GitLab activity, selected Slack channels, and Outline documents — to explain what worked, what could improve, and what to try next.
+Hephaestus reviews how developers plan, explain, and deliver changes in GitHub or GitLab. Each suggestion links back to the work and shows what to address next. Ask Heph why it matters or add context the review did not have.
 
 <div align="center">
   <picture>
-    <source media="(max-width: 520px) and (prefers-color-scheme: dark)" srcset="./docs/images/readme/landing-feedback-preview-mobile-dark.png">
-    <source media="(max-width: 520px) and (prefers-color-scheme: light)" srcset="./docs/images/readme/landing-feedback-preview-mobile-light.png">
-    <source media="(prefers-color-scheme: dark)" srcset="./docs/images/readme/landing-feedback-preview-dark.png">
-    <source media="(prefers-color-scheme: light)" srcset="./docs/images/readme/landing-feedback-preview-light.png">
-    <img alt="Example practice feedback on a focused change: Hephaestus notes that the change is easy to review and suggests explaining why it matters; the developer asks what to write, and Heph suggests a concise sentence." src="./docs/images/readme/landing-feedback-preview-light.png" width="744">
+    <source media="(prefers-color-scheme: dark)" srcset="./docs/images/readme/landing-hero-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="./docs/images/readme/landing-hero-light.png">
+    <img alt="A bulk-archive change shown with an unanswered product decision, review feedback, and a question from Heph." src="./docs/images/readme/landing-hero-light.png" width="1224">
   </picture>
-  <p><sub>One example of practice feedback and a follow-up with Heph.</sub></p>
 </div>
 
-Hephaestus is built for software engineering courses, open-source projects, and teams where mentors and maintainers cannot review every contribution themselves.
+It is built for software engineering courses, open-source projects, and engineering teams that want feedback to stay close to the work that prompted it.
 
 ## What Hephaestus does
 
-- **Practice feedback.** Hephaestus uses AI to review pull requests, merge requests, and issues against the engineering practices configured for a workspace. It can post the feedback as comments on the work.
-- **Heph, the AI mentor.** Developers can talk with Heph about feedback and recent issues, commits, reviews, and pull or merge requests. Heph is available in the web app and, when connected, in Slack.
-- **Project context.** Workspace admins can let Hephaestus use messages from selected, visibly monitored Slack channels and documents from selected Outline collections. Outline is a source of context; Hephaestus does not write to it.
-- **Workspaces.** Each workspace connects its own repositories, chooses its practice catalog, connects an AI model through any OpenAI-compatible endpoint, sets a monthly spending cap, and manages its members and teams.
-- **Optional recognition.** Workspace admins can enable achievements, leagues, a weekly leaderboard, and Slack digests of review activity.
+- **Connects feedback to the work.** Hephaestus reviews pull requests, merge requests, and issues against the practices configured for a workspace and points back to relevant evidence.
+- **Continues the conversation with Heph.** Developers can ask why a suggestion matters or explain context the review missed in the web app or Slack.
+- **Uses connected project context.** GitHub, GitLab, Slack, and Outline integrations provide repository activity, team conversations, and documentation.
+- **Keeps workspaces in control.** Admins configure repositories, practices, AI models, budgets, members, and integrations.
 
 ## How feedback works
 
-The loop starts with a developer's project work and the context around it. Hephaestus reviews the work against the engineering practices configured for the workspace, turns what it finds into feedback, and delivers that feedback where it can help.
+1. A workspace connects its GitHub or GitLab repositories and chooses the engineering practices it cares about.
+2. Hephaestus reviews relevant pull requests, merge requests, and issues for evidence of those practices.
+3. Hephaestus can deliver feedback alongside the contribution and in the web app, with the evidence behind it.
+4. Developers can ask Heph about the suggestion or explain context the review missed.
 
-<picture>
-  <source media="(max-width: 640px) and (prefers-color-scheme: dark)" srcset="./docs/images/readme/feedback-loop-mobile-dark.png">
-  <source media="(max-width: 640px) and (prefers-color-scheme: light)" srcset="./docs/images/readme/feedback-loop-mobile-light.png">
-  <source media="(max-width: 1024px) and (prefers-color-scheme: dark)" srcset="./docs/images/readme/feedback-loop-tablet-dark.png">
-  <source media="(max-width: 1024px) and (prefers-color-scheme: light)" srcset="./docs/images/readme/feedback-loop-tablet-light.png">
-  <source media="(prefers-color-scheme: dark)" srcset="./docs/images/readme/feedback-loop-dark.png">
-  <source media="(prefers-color-scheme: light)" srcset="./docs/images/readme/feedback-loop-light.png">
-  <img alt="Hephaestus feedback loop: project work and context are reviewed against workspace practices; practice feedback explains what worked, what could improve, and what to try next; it can appear alongside the work or in conversation with Heph; the developer decides whether to use, question, or skip it before their next piece of project work." src="./docs/images/readme/feedback-loop-light.png" width="1224">
-</picture>
+Developers decide whether the feedback fits their work.
 
-Developers decide what helps: use the feedback, question it, or skip it. The cycle continues with their next piece of project work. Hephaestus supports mentors, teachers, and maintainers by covering routine feedback. It does not replace their judgement or the relationships they build with developers.
+## Project origins
 
-## Project status
+Hephaestus is an [MIT-licensed](./LICENSE) open-source project developed by [Applied Education Technologies](https://aet.cit.tum.de/) at the [Technical University of Munich](https://www.tum.de/en/). It is named after the Greek god of blacksmiths and craftspeople.
+
+## Before upgrading
 
 > [!IMPORTANT]
-> **Hephaestus is still pre-1.0.** Until 1.0, a minor release can change configuration or APIs in ways that require action. If you self-host it, use the [latest release](https://github.com/ls1intum/Hephaestus/releases/latest), read its release notes and the [migration guide](./MIGRATION.md), and test upgrades in staging.
->
-> We are aiming for a stable **v1.0.0 in mid-September 2026**. Here, stable means [predictable rules](./docs/admin/compatibility-policy.mdx) for upgrades, configuration, Docker Compose, and the REST API — not that development stops.
->
-> Parts of this model already ship. For v1.0, the goal is to support them together as a stable product:
->
-> - **Project context:** work in GitHub and GitLab, selected Slack channels, and selected Outline documents.
-> - **Feedback delivery:** alongside work in GitHub or GitLab, in a personal view across projects, and in conversation with Heph in the web app or Slack.
->
-> Release gates take priority over the date. Follow the [v1.0 milestone](https://github.com/ls1intum/Hephaestus/milestone/5) and [release plan](https://github.com/ls1intum/Hephaestus/issues/1377) for current scope and progress.
+> Before upgrading a self-hosted deployment, read the [release notes](https://github.com/ls1intum/Hephaestus/releases/latest), [compatibility policy](./docs/admin/compatibility-policy.mdx), and [migration guide](./MIGRATION.md), then test the upgrade in staging.
 
 ## Get started
 
-- **TUM deployment:** [open the web app](https://hephaestus.aet.cit.tum.de).
-- **Documentation:** read the [user, administrator, and contributor guides](https://ls1intum.github.io/Hephaestus/).
-- **Self-hosting:** follow the [install guide](https://ls1intum.github.io/Hephaestus/admin/install) ([INSTALL.md](INSTALL.md)) for the supported Docker Compose path.
-- **Development:** use the [local development guide](https://ls1intum.github.io/Hephaestus/contributor/local-development), and explore the web interface in [Storybook](https://main--66a8981a27ced8fef3190d41.chromatic.com/).
+- **Open the hosted app:** visit the [TUM deployment](https://hephaestus.aet.cit.tum.de).
+- **Learn how it works:** read the [user guide](https://ls1intum.github.io/Hephaestus/user/overview).
+- **Run your own deployment:** follow the [self-hosting guide](https://ls1intum.github.io/Hephaestus/admin/install) or start with [INSTALL.md](INSTALL.md).
+- **Contribute:** use the [local development guide](https://ls1intum.github.io/Hephaestus/contributor/local-development) and explore the interface in [Storybook](https://main--66a8981a27ced8fef3190d41.chromatic.com/).
 
 ## Get help
 
@@ -89,8 +73,4 @@ Developers decide what helps: use the feedback, question it, or skip it. The cyc
 
 ## Contributing
 
-Contributions are welcome. Before you start, read [CONTRIBUTING.md](./CONTRIBUTING.md) and the [Code of Conduct](./CODE_OF_CONDUCT.md). They cover the development workflow, pull request requirements, community expectations, and the project's identity requirements for contributors.
-
-The project follows a pull request contribution model and GitHub's [Acceptable Use Policies](https://docs.github.com/en/site-policy/acceptable-use-policies).
-
-The project is named after Hephaestus, the Greek god of blacksmiths and craftsmen.
+Contributions are welcome. [CONTRIBUTING.md](./CONTRIBUTING.md) explains how to set up the project, propose a change, run the quality checks, and open a pull request. Participation in the project is governed by the [Code of Conduct](./CODE_OF_CONDUCT.md).

docs/docusaurus.config.ts

@@ -2,21 +2,15 @@ import {themes as prismThemes} from 'prism-react-renderer';
 import type {Config} from '@docusaurus/types';
 import type * as Preset from '@docusaurus/preset-classic';
 
-// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
-
 const envBaseUrl = process.env.DOCUSAURUS_BASE_URL;
 
 const config: Config = {
   title: 'Hephaestus Documentation',
-  tagline: 'Feedback on how you work',
+  tagline: "Learn from the work you're already doing",
   favicon: 'img/favicon.ico',
 
-  // Future flags and performance optimizations
-  // See https://docusaurus.io/docs/api/docusaurus-config#future
   future: {
     v4: true,
-    // Docusaurus Faster: Uses Rspack, SWC, and LightningCSS for 2-4x faster builds
-    // https://docusaurus.io/blog/releases/3.6#docusaurus-faster
     faster: {
       swcJsLoader: true,
       swcJsMinimizer: true,
@@ -39,9 +33,6 @@ const config: Config = {
   onDuplicateRoutes: 'throw',
   trailingSlash: false,
 
-  // Even if you don't use internationalization, you can use this field to set
-  // useful metadata like html lang. For example, if your site is Chinese, you
-  // may want to replace "en" with "zh-Hans".
   i18n: {
     defaultLocale: 'en',
     locales: ['en'],
@@ -71,15 +62,12 @@ const config: Config = {
         theme: {
           customCss: './src/css/custom.css',
         },
-        // Sitemap generation with lastmod for SEO
         sitemap: {
           lastmod: 'datetime',
           changefreq: 'weekly',
           priority: 0.5,
           filename: 'sitemap.xml',
         },
-        // Google Tag Manager can be configured here if needed
-        // gtag: { trackingID: 'G-XXXXXXXXXX' },
       } satisfies Preset.Options,
     ],
   ],
@@ -152,7 +140,7 @@ const config: Config = {
       {
         name: 'description',
         content:
-          'Hephaestus gives developers practice feedback on software project work, plus an AI mentor for talking through feedback and next steps.',
+          'Hephaestus gives developers practice feedback on software project work and lets them discuss it with Heph, its conversational AI mentor.',
       },
       {name: 'keywords', content: 'Hephaestus, AI mentor, code review feedback, software engineering practices, TUM'},
       {name: 'twitter:card', content: 'summary_large_image'},
@@ -161,7 +149,7 @@ const config: Config = {
       {
         name: 'twitter:description',
         content:
-          'Hephaestus gives developers practice feedback on software project work, plus an AI mentor for talking through feedback and next steps.',
+          'Hephaestus gives developers practice feedback on software project work and lets them discuss it with Heph, its conversational AI mentor.',
       },
     ],
     navbar: {
@@ -252,7 +240,7 @@ const config: Config = {
           ],
         },
         {
-          title: 'Community',
+          title: 'Project',
           items: [
             {
               label: 'Applied Education Technologies',
@@ -265,15 +253,14 @@ const config: Config = {
           ],
         },
       ],
-      copyright: `© ${new Date().getFullYear()} Technical University of Munich · Built with ❤️ by the Hephaestus Team at Applied Education Technologies (AET)`,
+      copyright: `Hephaestus is an MIT-licensed open-source project developed by Applied Education Technologies at the Technical University of Munich.`,
     },
     docs: {
       sidebar: {
         hideable: true,
         autoCollapseCategories: true,
       },
     },
-    // Table of contents configuration
     tableOfContents: {
       minHeadingLevel: 2,
       maxHeadingLevel: 4,