feat: clarify profiles and workspaces

[Michaelyklam]

Thinking Path

• Issue Feature request: Improve/clarify profiles #2147 shows that profiles and workspaces are easy to confuse, especially for users coming from OpenClaw-style role agents.
• Michael clarified in the issue that profiles are first-class agent/persona peers, while workspaces are WebUI project/file scopes.
• The smallest useful product slice is not a new profile-template system; it is inline guidance at the moment users manage profiles.
• The Profiles panel already has room for a lightweight explanatory card, so this PR adds that copy without changing profile/workspace behavior.
• Review feedback correctly pointed out that the Profiles panel is localized, so the explainer now follows the same i18n path.

What Changed

• Adds a clickable localized "Profiles vs workspaces" help card at the top of the Profiles panel.
• Adds a detail view that explains:
  • profiles = identity, memory, skills, model/provider config, and tools;
  • workspaces = project/product folders and file context;
  • profiles answer "who is working?" while workspaces answer "where are they working?".
• Wires the new copy through static/i18n.js instead of hardcoded English strings.
• Gives the help card a subtle distinct visual treatment so it reads as guidance, not a profile entry.
• Keeps the help card visible even when no profiles are returned.
• Adds source-level regression tests for the i18n wiring, copy, card styling, and empty-state behavior.
• Updates CHANGELOG.md for the user-facing clarification.

Why It Matters

Users should not have to read a GitHub comment to understand whether to create profiles for roles like researcher/marketer/developer or workspaces for products/repos. This puts the explanation directly in the profile-management surface and preserves localization parity for the panel.

Refs #2147.

Verification

• node --check static/panels.js
• node --check static/i18n.js
• env -u HERMES_CONFIG_PATH -u HERMES_WEBUI_HOST /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/test_issue2147_profile_workspace_copy.py -q — 5 passed
• git diff --check

Risks / Follow-ups

• This is a narrow copy/UI clarification, not a profile-template system or a redesign of scheduled-task/profile scoping.
• No browser screenshot is attached; the change is static copy in an existing card/detail layout and is covered by source-level tests.
• A future PR can add richer profile templates if maintainers choose that direction.

Model Used

AI-assisted change with repository inspection, targeted editing, and shell-based test verification.

[nesquena-hermes]

Diagnosis

Read static/panels.js:4465-4548 on the PR branch (the new help card + _renderProfileConceptHelp detail view) and the surrounding loadProfilesPanel() to confirm the insertion point, plus tests/test_issue2147_profile_workspace_copy.py for the assertions. Cross-referenced #2147's comment thread where the maintainer wrote the canonical explanation ("Profiles act sort of like first class subagents... Workspaces are a WebUI extension..."). The card copy matches that framing well — the dichotomy of "who is working" vs "where they are working" is concise and accurate.

One blocker: i18n bypass

The Profiles panel is fully internationalized. Every neighboring string in loadProfilesPanel() already uses t(...):

// static/panels.js (existing master, near where the help card is inserted)
panel.innerHTML = `<div ...>${esc(t('profiles_no_profiles'))}</div>`;
// ...
if (p.gateway_running) /* uses t('profile_gateway_running') etc */
if (p.skill_count) meta.push(t('profile_skill_count', p.skill_count));
const activeBadge = isActive ? `... ${esc(t('profile_active'))} ...` : '';

But the new help card and _renderProfileConceptHelp() ship 6 user-facing English strings hardcoded:

// static/panels.js (this PR)
<div class="profile-card-name">Profiles vs workspaces</div>
<div class="profile-card-meta">Use profiles for how the agent works; use workspaces for what files it works on.</div>
// ...
title.textContent = 'Profiles vs workspaces';
<div class="detail-card-title">Use profiles for how; workspaces for what</div>
<div class="detail-row-value">Agent identity, memory, skills, model/provider config...</div>
<div class="detail-row-value">Project or product folders on disk...</div>

static/i18n.js already has 10 locales (each with a profiles_no_profiles key around lines 1064, 2245, 3431, 4369, 5507, 6795, 7730, 8852, 11226, 12328). Shipping the help card as English-only is a regression for the 7+ non-English locales — they'll get a panel where every line is translated except the new "Profiles vs workspaces" introduction.

Suggested minimum: add a small i18n bundle entry per locale, then t('profiles_vs_workspaces_title'), t('profiles_vs_workspaces_subtitle'), t('profiles_vs_workspaces_profile_body'), etc. The detail view's three detail-row-value paragraphs can stay as separate keys to make translation chunks manageable.

Smaller follow-ups

1. Source-level test fragility. tests/test_issue2147_profile_workspace_copy.py:13-32 asserts on raw English substrings in static/panels.js. Once you wire i18n, those assertions will need to switch to checking either the t(...) call sites or the English entry in static/i18n.js. The current shape locks in the bypass.
2. Missing CSS for .profile-help-card. static/style.css:1743-1750 defines .profile-card, but profile-help-card has no rule. As written the card inherits the regular cursor:pointer from .profile-card (good — it's clickable) but it'll look identical to a profile entry, which could be confusing in the empty-state where it's the only item. A small visual differentiator (subtle border or muted background) would help users understand it's a help card, not a profile.
3. data.active || 'default' thread-through. explainer.onclick = () => _renderProfileConceptHelp(data.active || 'default'); passes activeName to _renderProfileConceptHelp(activeName), but the helper body never reads the argument. Either remove the parameter or use it (e.g. add "Active: foo" in the detail card). Right now it's dead.

Verdict

The product direction is right, the copy matches the maintainer's own explanation, and the scope (lightweight inline guidance, not a profile-template system) is the correct first slice. The i18n gap is the only thing I'd actually require before merge — everything else is polish. Once i18n is wired and the test assertions point at i18n keys instead of raw English, this should be straightforward to land.

[Michaelyklam]

Thanks — pushed a follow-up in cff6570 that addresses the review blocker and the cheap cleanup items:

• moved the Profiles vs workspaces card/detail copy behind t(...) keys in static/i18n.js
• updated the regression tests to assert i18n wiring instead of hardcoded English in static/panels.js
• added a subtle .profile-help-card style so the guidance card is visually distinct from profile entries
• removed the unused _renderProfileConceptHelp(activeName) parameter
• refreshed the changelog/PR body to mention the localized explainer

Verification:

• node --check static/panels.js
• node --check static/i18n.js
• env -u HERMES_CONFIG_PATH -u HERMES_WEBUI_HOST /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/test_issue2147_profile_workspace_copy.py -q — 5 passed
• git diff --check

[nesquena-hermes]

Shipped in v0.51.71 ✅

Stage-364 release shipped at #2352. Merged commit 761cf55 into master. Tag v0.51.71 pushed.

Verified before release:

• Full pytest: 5713 passed, 0 failed
• QA harness: 20/20 pass
• Opus advisor: independently verified your changes against source, APPROVE with one SHOULD-FIX caught for PR Add WebUI run event journal replay #2283 (now fixed inline)
• Browser sanity: features confirmed live with no console errors
• Agent self-verification (TWO-LAYER catch, first live use): PR Add WebUI run event journal replay #2283 producer→consumer chain verified end-to-end via unmocked production reader chain

Maintainer fix applied inline to #2283 (per CHANGELOG): Opus caught that live SSE frames carried no id: field, which would have caused replay-after-mid-stream-error to double-render every token. Fixed by adding STREAM_LAST_EVENT_ID side-channel dict in api/config.py; queue tuple shape preserved as (event, data) to avoid breaking existing tests. 6 regression tests added.

Thanks for the contribution! Closing now.