Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix: improve getting started (#5264)

Peter Chinman2d9a00d84ce0
diff --git a/Cargo.lock b/Cargo.lock
index d56c9d81d1..b21aa6d441 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -969,7 +969,6 @@ dependencies = [
"aws-sdk-sqs",
"axum",
"base64 0.22.1",
- "bot_id",
"channels",
"chrono",
"comms_db_client",
diff --git a/apps/web/src/features/getting-started/getting-started-rows.tsx b/apps/web/src/features/getting-started/getting-started-rows.tsx
index b952fd95f4..2973c50001 100644
--- a/apps/web/src/features/getting-started/getting-started-rows.tsx
+++ b/apps/web/src/features/getting-started/getting-started-rows.tsx
@@ -8,9 +8,12 @@ import type {
} from './getting-started-types';
/**
- * One activating action in the shared home-row style (icon + title +
- * description, full width), with a trailing checkbox that fills once the
- * action completes. Rows stay clickable when complete.
+ * One activating action in the shared home-row style (icon + title, full
+ * width), with a trailing checkbox that fills once the action completes. Rows
+ * stay clickable when complete.
+ *
+ * `action.description` is deliberately not rendered for now — we're trying
+ * title-only rows. The copy is kept on the action data so it can come back.
*/
export function ActionRow(props: {
action: GettingStartedAction;
@@ -28,7 +31,6 @@ export function ActionRow(props: {
</span>
<div class="min-w-0 flex-1">
<div class="text-sm font-medium text-ink">{props.action.title}</div>
- <div class="text-xs text-ink-muted">{props.action.description}</div>
</div>
<InlineCheckbox checked={props.complete} />
</button>
diff --git a/apps/web/src/features/getting-started/getting-started.tsx b/apps/web/src/features/getting-started/getting-started.tsx
index 328e7b66c4..4473f47a8f 100644
--- a/apps/web/src/features/getting-started/getting-started.tsx
+++ b/apps/web/src/features/getting-started/getting-started.tsx
@@ -1,5 +1,6 @@
import { DOCS_BASE } from '@app/constants/docs-links';
import { HomeBackfillProgress } from '@app/features/home/home-backfill-progress';
+import { InteractiveOnboardingModal } from '@app/features/onboarding/InteractiveOnboardingModal';
import { useSplitLayout } from '@components/app/split-layout/layout';
import type { SplitContent } from '@components/app/split-layout/layoutManager';
import { useSplitPanelOrThrow } from '@components/app/split-layout/layoutUtils';
@@ -19,6 +20,7 @@ import { createChat } from '@core/util/create';
import { AnimatedProfileIcon } from '@icon/wide-profile';
import BookOpenIcon from '@phosphor/book-open.svg';
import PaletteIcon from '@phosphor/palette.svg';
+import PlayCircleIcon from '@phosphor/play-circle.svg';
import PlugsIcon from '@phosphor/plugs.svg';
import { useGithubLinkStatusQuery } from '@queries/auth/github-link';
import { isRealNamePart, useOwnUserName } from '@queries/auth/user-name-self';
@@ -31,7 +33,7 @@ import {
lightModeTheme,
themeMode,
} from '@theme/signals/themeSignals';
-import { createEffect, For, on, onMount, Show } from 'solid-js';
+import { createEffect, createSignal, For, on, onMount, Show } from 'solid-js';
import { AGENT_EXAMPLES } from './agent-examples';
import { ActionRow, SectionHeader } from './getting-started-rows';
import {
@@ -81,6 +83,11 @@ function GettingStartedContent() {
const starterDocs = useStarterDocsQuery();
const hasPaidAccess = useHasPaidAccess();
+ // The interactive tutorial, replayed on demand. Root auto-opens its own copy
+ // for first-time users; this one is always a replay, so it never passes
+ // isFirstTimeOnboarding.
+ const [tutorialOpen, setTutorialOpen] = createSignal(false);
+
/**
* Open content beside the list: re-engage a manually-closed Viewer first so
* the open lands there instead of replacing this panel, then route through
@@ -166,6 +173,13 @@ function GettingStartedContent() {
id: 'basics',
title: 'Set up your account',
actions: [
+ {
+ id: 'play-tutorial',
+ icon: PlayCircleIcon,
+ title: 'Play the Macro tutorial',
+ description: "Take a quick tour of Macro's core features",
+ onActivate: () => setTutorialOpen(true),
+ },
{
id: 'how-to-guide',
icon: BookOpenIcon,
@@ -284,6 +298,10 @@ function GettingStartedContent() {
</For>
</div>
</div>
+ <InteractiveOnboardingModal
+ open={tutorialOpen()}
+ onOpenChange={setTutorialOpen}
+ />
</main>
);
}
diff --git a/services/authentication_service/Cargo.toml b/services/authentication_service/Cargo.toml
index 685aa769e8..8e7743065e 100644
--- a/services/authentication_service/Cargo.toml
+++ b/services/authentication_service/Cargo.toml
@@ -41,7 +41,6 @@ aws-sdk-sesv2 = { workspace = true }
aws-sdk-sqs = { workspace = true }
axum = { workspace = true, features = ["macros"] }
base64 = { workspace = true }
-bot_id = { path = "../../crates/bot_id" }
channels = { path = "../../crates/channels", default-features = false, features = [
"outbound",
] }
diff --git a/services/authentication_service/src/api/webhooks/user/create_user_webhook.rs b/services/authentication_service/src/api/webhooks/user/create_user_webhook.rs
index dc970425c0..904920b846 100644
--- a/services/authentication_service/src/api/webhooks/user/create_user_webhook.rs
+++ b/services/authentication_service/src/api/webhooks/user/create_user_webhook.rs
@@ -28,7 +28,6 @@ use macro_user_id::{
user_id::MacroUserIdStr,
};
use model::authentication::webhooks::{FusionAuthUserWebhook, User as FusionAuthWebhookUser};
-use model::document_storage_service_internal::StarterDocHowToGuide;
use model_entity::EntityType;
use std::collections::HashSet;
use teams::domain::team_repo::TeamService;
@@ -353,9 +352,7 @@ async fn create_user_webhook(ctx: &ApiContext, req: FusionAuthUserWebhook) -> an
let email = email.clone();
let support_channel_name = support_channel_name.clone();
async move {
- let how_to_guide =
- initialize_starter_docs_with_retries(&document_storage_service_client, &user_id)
- .await;
+ initialize_starter_docs_with_retries(&document_storage_service_client, &user_id).await;
let owner_id = match MacroUserIdStr::try_from(user_id) {
Ok(owner_id) => owner_id,
@@ -406,14 +403,9 @@ async fn create_user_webhook(ctx: &ApiContext, req: FusionAuthUserWebhook) -> an
tracing::error!(error=?e, channel_id=%channel.id, %email, "failed to favorite Macro support channel");
}
- let _ = post_support_channel_welcome(
- channel_service.as_ref(),
- &channel.id,
- owner_id,
- how_to_guide.as_ref(),
- )
- .await
- .inspect_err(|e| {
+ let _ = post_support_channel_welcome(channel_service.as_ref(), &channel.id, owner_id)
+ .await
+ .inspect_err(|e| {
tracing::error!(error=?e, channel_id=%channel.id, %email, "failed to post Macro support welcome message");
});
}
@@ -431,17 +423,16 @@ async fn create_user_webhook(ctx: &ApiContext, req: FusionAuthUserWebhook) -> an
Ok(())
}
-/// Seed the starter documents with retries, returning the "Macro how to
-/// guide" reference when it could be resolved.
+/// Seed the starter documents with retries.
async fn initialize_starter_docs_with_retries(
client: &document_storage_service_client::DocumentStorageServiceClient,
user_id: &str,
-) -> Option<StarterDocHowToGuide> {
+) {
const MAX_ATTEMPTS: u32 = 3;
const RETRY_DELAY_SECS: u64 = 2;
for attempt in 1..=MAX_ATTEMPTS {
match client.initialize_starter_docs(user_id).await {
- Ok(how_to_guide) => return how_to_guide,
+ Ok(_) => return,
Err(e) if attempt < MAX_ATTEMPTS => {
tracing::warn!(error=?e, attempt, "failed to initialize starter docs, retrying");
tokio::time::sleep(std::time::Duration::from_secs(RETRY_DELAY_SECS)).await;
@@ -451,7 +442,6 @@ async fn initialize_starter_docs_with_retries(
}
}
}
- None
}
/// Initializes the experiments for a provided user
diff --git a/services/authentication_service/src/service/user/support_channel_welcome.rs b/services/authentication_service/src/service/user/support_channel_welcome.rs
index efc349315d..7471688057 100644
--- a/services/authentication_service/src/service/user/support_channel_welcome.rs
+++ b/services/authentication_service/src/service/user/support_channel_welcome.rs
@@ -1,13 +1,11 @@
use std::future::Future;
-use bot_id::{MACRO_AI_BOT_ID, MACRO_AI_NAME};
use channels::domain::{
models::{PostMessageNotificationPolicy, PostMessageRequest, Sender, SimpleMention},
ports::ChannelService,
};
use macro_user_id::user_id::MacroUserIdStr;
-use mention_utils::serialize::{bot_mention, document_mention, user_mention};
-use model::document_storage_service_internal::StarterDocHowToGuide;
+use mention_utils::serialize::user_mention;
use rootcause::{Report, prelude::ResultExt};
use uuid::Uuid;
@@ -20,13 +18,13 @@ const TEO_EMAIL: &str = "[email protected]";
/// The channel operation required to post a new user's welcome messages.
pub trait SupportChannelMessageGateway: Send + Sync + 'static {
- /// Post a welcome message, returning the created message id.
+ /// Post a welcome message.
fn post_message(
&self,
actor: Sender,
channel_id: Uuid,
request: PostMessageRequest,
- ) -> impl Future<Output = Result<Uuid, Report>> + Send;
+ ) -> impl Future<Output = Result<(), Report>> + Send;
}
impl<T> SupportChannelMessageGateway for T
@@ -38,13 +36,12 @@ where
actor: Sender,
channel_id: Uuid,
request: PostMessageRequest,
- ) -> Result<Uuid, Report> {
- let response = ChannelService::post_message(self, actor, channel_id, request)
+ ) -> Result<(), Report> {
+ ChannelService::post_message(self, actor, channel_id, request)
.await
.context("failed to post Macro support welcome message")?;
- Ok(Uuid::parse_str(&response.id)
- .context("posted Macro support welcome message returned an invalid id")?)
+ Ok(())
}
}
@@ -53,15 +50,11 @@ fn support_user(email: &str) -> Result<MacroUserIdStr<'static>, Report> {
.context_with(|| format!("invalid Macro support user email: {email}"))?)
}
-/// Post the welcome script in a newly created support channel: Julia's
-/// welcome message, a scripted reply from the Macro assistant (posted
-/// directly as the bot — the model is never invoked), and Julia's feedback
-/// prompt.
+/// Post Julia's welcome message in a newly created support channel.
pub async fn post_support_channel_welcome(
gateway: &impl SupportChannelMessageGateway,
channel_id: &str,
new_user: MacroUserIdStr<'static>,
- how_to_guide: Option<&StarterDocHowToGuide>,
) -> Result<(), Report> {
let channel_id =
Uuid::parse_str(channel_id).context("support channel returned an invalid id")?;
@@ -70,16 +63,6 @@ pub async fn post_support_channel_welcome(
let teo = support_user(TEO_EMAIL)?;
let new_user_mention = user_mention(&new_user)?;
- let macro_mention = bot_mention(MACRO_AI_BOT_ID, MACRO_AI_NAME)?;
- // When the guide could not be seeded the document paragraph keeps its
- // point but drops the example mention.
- let document_example = match how_to_guide {
- Some(guide) => format!(
- ", like this: {}",
- document_mention(&guide.document_id, &guide.document_name)?
- ),
- None => String::new(),
- };
let welcome = format!(
"Hey {new_user_mention},\n\
@@ -88,27 +71,18 @@ Welcome to Macro, we're excited for you to try it out.\n\
\n\
This is your own personal support Channel, with {} (ceo) and {} (cto) and me (julia).\n\
\n\
-Channels are how you stay in touch with other people on Macro.\n\
-\n\
-You can @mention people to get their attention. They'll get a separate notification in their inbox (like you'll see for this message).\n\
-\n\
-You can @mention documents{document_example}. Mentioning a document shares it with the other participants.\n\
-\n\
-You can even @mention our chat assistant, {macro_mention}. Say hi to {new_user_mention}, {macro_mention}.",
+If you have any feedback or find any bugs let us know here.",
user_mention(&jacob)?,
user_mention(&teo)?,
);
- // Keep Jacob, Teo, Macro, and the guide visually mentioned without
- // tracking them: tracked mentions would notify Jacob and Teo (and the
- // support team about the guide) on every signup, and a tracked bot
- // mention could trigger a real model reply if bot triggers were ever
- // wired into this service. Julia is the sender, so the channel
- // notification policy excludes her automatically.
+ // Keep Jacob and Teo visually mentioned without tracking them: tracked
+ // mentions would notify them on every signup. Julia is the sender, so the
+ // channel notification policy excludes her automatically.
let mentions = [&new_user].into_iter().map(SimpleMention::user).collect();
- let welcome_message_id = gateway
+ gateway
.post_message(
- Sender::new_from_user(julia.clone()),
+ Sender::new_from_user(julia),
channel_id,
PostMessageRequest {
content: welcome,
@@ -122,52 +96,5 @@ You can even @mention our chat assistant, {macro_mention}. Say hi to {new_user_m
)
.await?;
- // The scripted assistant reply, threaded under the welcome message and
- // authored by the Macro bot itself. The new user's mention stays
- // visual-only: they already get the mention notification from the
- // welcome message above.
- let assistant_reply = format!(
- "Hey {new_user_mention}! 👋 Welcome to Macro — great to have you here.\n\
-\n\
-I'm the built-in assistant. You can @mention me anytime in a channel or chat and I'll help out: summarizing threads, drafting emails, digging through your docs and messages, managing tasks, whatever you need. Just ask.\n\
-\n\
-Excited for you to dive in."
- );
-
- gateway
- .post_message(
- Sender::new_from_bot(MACRO_AI_BOT_ID),
- channel_id,
- PostMessageRequest {
- content: assistant_reply,
- mentions: Vec::new(),
- thread_id: Some(welcome_message_id),
- attachments: Vec::new(),
- nonce: None,
- notification_policy: PostMessageNotificationPolicy::Default,
- // Julia's message asks Macro to say hi, so she is the
- // triggering user — the same attribution a real
- // mention-triggered agent reply would carry.
- triggered_by: Some(julia.to_string()),
- },
- )
- .await?;
-
- gateway
- .post_message(
- Sender::new_from_user(julia),
- channel_id,
- PostMessageRequest {
- content: "If you have any feedback or find any bugs let us know here.".to_string(),
- mentions: Vec::new(),
- thread_id: None,
- attachments: Vec::new(),
- nonce: None,
- notification_policy: PostMessageNotificationPolicy::Default,
- triggered_by: None,
- },
- )
- .await?;
-
Ok(())
}
diff --git a/services/authentication_service/src/service/user/support_channel_welcome/test.rs b/services/authentication_service/src/service/user/support_channel_welcome/test.rs
index abb1adb74c..126fee97c1 100644
--- a/services/authentication_service/src/service/user/support_channel_welcome/test.rs
+++ b/services/authentication_service/src/service/user/support_channel_welcome/test.rs
@@ -8,7 +8,6 @@ struct RecordingGateway {
}
struct PostedWelcomeMessage {
- id: Uuid,
actor: Sender,
channel_id: Uuid,
request: PostMessageRequest,
@@ -20,15 +19,13 @@ impl SupportChannelMessageGateway for RecordingGateway {
actor: Sender,
channel_id: Uuid,
request: PostMessageRequest,
- ) -> Result<Uuid, Report> {
- let id = Uuid::new_v4();
+ ) -> Result<(), Report> {
self.posted.lock().unwrap().push(PostedWelcomeMessage {
- id,
actor,
channel_id,
request,
});
- Ok(id)
+ Ok(())
}
}
@@ -36,17 +33,9 @@ fn user_id(email: &str) -> MacroUserIdStr<'static> {
MacroUserIdStr::try_from_email(email).unwrap()
}
-fn how_to_guide() -> StarterDocHowToGuide {
- StarterDocHowToGuide {
- document_id: "1af9022e-6d0d-4f9c-8bc4-4b1f9a2f47d0".to_string(),
- document_name: "Macro how to guide".to_string(),
- }
-}
-
const NEW_USER_MENTION: &str = "<m-user-mention>{\"userId\":\"macro|[email protected]\",\"email\":\"[email protected]\"}</m-user-mention>";
-const MACRO_MENTION: &str = "<m-user-mention>{\"userId\":\"bot|00000000-0000-0000-0000-00000000a1a1\",\"email\":\"Macro\"}</m-user-mention>";
-fn expected_welcome(document_example: &str) -> String {
+fn expected_welcome() -> String {
format!(
concat!(
"Hey {new_user},\n",
@@ -55,35 +44,14 @@ fn expected_welcome(document_example: &str) -> String {
"\n",
"This is your own personal support Channel, with <m-user-mention>{{\"userId\":\"macro|[email protected]\",\"email\":\"[email protected]\"}}</m-user-mention> (ceo) and <m-user-mention>{{\"userId\":\"macro|[email protected]\",\"email\":\"[email protected]\"}}</m-user-mention> (cto) and me (julia).\n",
"\n",
- "Channels are how you stay in touch with other people on Macro.\n",
- "\n",
- "You can @mention people to get their attention. They'll get a separate notification in their inbox (like you'll see for this message).\n",
- "\n",
- "You can @mention documents{document_example}. Mentioning a document shares it with the other participants.\n",
- "\n",
- "You can even @mention our chat assistant, {macro_bot}. Say hi to {new_user}, {macro_bot}.",
- ),
- new_user = NEW_USER_MENTION,
- macro_bot = MACRO_MENTION,
- document_example = document_example,
- )
-}
-
-fn expected_assistant_reply() -> String {
- format!(
- concat!(
- "Hey {new_user}! 👋 Welcome to Macro — great to have you here.\n",
- "\n",
- "I'm the built-in assistant. You can @mention me anytime in a channel or chat and I'll help out: summarizing threads, drafting emails, digging through your docs and messages, managing tasks, whatever you need. Just ask.\n",
- "\n",
- "Excited for you to dive in.",
+ "If you have any feedback or find any bugs let us know here.",
),
new_user = NEW_USER_MENTION,
)
}
#[tokio::test]
-async fn posts_the_welcome_script_with_the_guide_mentioned() {
+async fn posts_the_welcome_message() {
let channel_id = Uuid::new_v4();
let gateway = RecordingGateway::default();
@@ -91,31 +59,18 @@ async fn posts_the_welcome_script_with_the_guide_mentioned() {
&gateway,
&channel_id.to_string(),
user_id("[email protected]"),
- Some(&how_to_guide()),
)
.await
.unwrap();
let posted = gateway.posted.lock().unwrap();
- let [welcome, reply, feedback] = posted.as_slice() else {
- panic!(
- "expected exactly three posted messages, got {}",
- posted.len()
- );
+ let [welcome] = posted.as_slice() else {
+ panic!("expected exactly one posted message, got {}", posted.len());
};
- assert!(
- posted
- .iter()
- .all(|message| message.channel_id == channel_id)
- );
+ assert_eq!(welcome.channel_id, channel_id);
assert_eq!(welcome.actor.as_user(), Some(&user_id("[email protected]")));
- assert_eq!(
- welcome.request.content,
- expected_welcome(
- ", like this: <m-document-mention>{\"documentId\":\"1af9022e-6d0d-4f9c-8bc4-4b1f9a2f47d0\",\"blockName\":\"md\",\"documentName\":\"Macro how to guide\",\"blockParams\":{},\"collapsed\":false}</m-document-mention>"
- )
- );
+ assert_eq!(welcome.request.content, expected_welcome());
assert_eq!(
welcome.request.mentions,
vec![SimpleMention::user(&user_id("[email protected]"))]
@@ -128,61 +83,16 @@ async fn posts_the_welcome_script_with_the_guide_mentioned() {
PostMessageNotificationPolicy::MentionsOnly
);
assert_eq!(welcome.request.triggered_by, None);
-
- assert_eq!(reply.actor, Sender::new_from_bot(MACRO_AI_BOT_ID));
- assert_eq!(reply.request.content, expected_assistant_reply());
- assert!(reply.request.mentions.is_empty());
- assert_eq!(reply.request.thread_id, Some(welcome.id));
- assert_eq!(
- reply.request.triggered_by,
- Some("macro|[email protected]".to_string())
- );
- assert_eq!(
- reply.request.notification_policy,
- PostMessageNotificationPolicy::Default
- );
-
- assert_eq!(feedback.actor.as_user(), Some(&user_id("[email protected]")));
- assert_eq!(
- feedback.request.content,
- "If you have any feedback or find any bugs let us know here."
- );
- assert!(feedback.request.mentions.is_empty());
- assert_eq!(feedback.request.thread_id, None);
- assert_eq!(feedback.request.triggered_by, None);
-}
-
-#[tokio::test]
-async fn omits_the_document_example_when_the_guide_is_missing() {
- let channel_id = Uuid::new_v4();
- let gateway = RecordingGateway::default();
-
- post_support_channel_welcome(
- &gateway,
- &channel_id.to_string(),
- user_id("[email protected]"),
- None,
- )
- .await
- .unwrap();
-
- let posted = gateway.posted.lock().unwrap();
- assert_eq!(posted.len(), 3);
- assert_eq!(posted[0].request.content, expected_welcome(""));
}
#[tokio::test]
async fn rejects_an_invalid_channel_id_without_posting() {
let gateway = RecordingGateway::default();
- let error = post_support_channel_welcome(
- &gateway,
- "not-a-uuid",
- user_id("[email protected]"),
- None,
- )
- .await
- .unwrap_err();
+ let error =
+ post_support_channel_welcome(&gateway, "not-a-uuid", user_id("[email protected]"))
+ .await
+ .unwrap_err();
assert_eq!(
error.downcast_current_context::<&str>().copied(),