Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
Add onboarding guide initialization for new users (#4559)
Jacob Beckerman3ead54da7e93
diff --git a/rust/cloud-storage/authentication_service/src/api/webhooks/user/create_user_webhook.rs b/rust/cloud-storage/authentication_service/src/api/webhooks/user/create_user_webhook.rsindex 9626c58e2c..9a851265a4 100644--- a/rust/cloud-storage/authentication_service/src/api/webhooks/user/create_user_webhook.rs+++ b/rust/cloud-storage/authentication_service/src/api/webhooks/user/create_user_webhook.rs@@ -182,6 +182,33 @@ async fn create_user_webhook(ctx: &ApiContext, req: FusionAuthUserWebhook) -> an}});+ // Seed the "Macro how to guide" document and pin it to the new user's+ // sidebar favorites. Fire-and-forget with retries — signup must not fail+ // if document storage is temporarily unavailable.+ tokio::spawn({+ let document_storage_service_client = ctx.document_storage_service_client.clone();+ let user_id = user_id.clone();+ async move {+ const MAX_ATTEMPTS: u32 = 3;+ const RETRY_DELAY_SECS: u64 = 2;+ for attempt in 1..=MAX_ATTEMPTS {+ match document_storage_service_client+ .initialize_how_to_guide(&user_id)+ .await+ {+ Ok(()) => return,+ Err(e) if attempt < MAX_ATTEMPTS => {+ tracing::warn!(error=?e, attempt, "failed to initialize how to guide, retrying");+ tokio::time::sleep(std::time::Duration::from_secs(RETRY_DELAY_SECS)).await;+ }+ Err(e) => {+ tracing::error!(error=?e, "failed to initialize how to guide after {MAX_ATTEMPTS} attempts");+ }+ }+ }+ }+ });+tracing::trace!(email, fusionauth_user_id, elapsed=?start_time.elapsed(), "created user");// Allow to fail silentlydiff --git a/rust/cloud-storage/document_storage_service/src/api/context.rs b/rust/cloud-storage/document_storage_service/src/api/context.rsindex 0a0810e12a..5d07252f6d 100644--- a/rust/cloud-storage/document_storage_service/src/api/context.rs+++ b/rust/cloud-storage/document_storage_service/src/api/context.rs@@ -341,6 +341,7 @@ pub(crate) struct ApiContext {#[cfg(feature = "graphql")]pub graphql_notification_reader: Arc<dyn graphql_soup::SoupNotificationEdgeReader>,pub favorites_state: DssFavoritesState,+ pub favorites_service: Arc<FavoritesServiceType>,pub foreign_entity_state: DssForeignEntityState,pub sqs_client: Arc<sqs_client::SQS>,pub contacts_ingress: Arc<SqsContactsIngress<SqsContactsQueue>>,diff --git a/rust/cloud-storage/document_storage_service/src/api/documents/initialize_how_to_guide.rs b/rust/cloud-storage/document_storage_service/src/api/documents/initialize_how_to_guide.rsnew file mode 100644index 0000000000..c883bdb6d6--- /dev/null+++ b/rust/cloud-storage/document_storage_service/src/api/documents/initialize_how_to_guide.rs@@ -0,0 +1,70 @@+use crate::api::context::ApiContext;+use axum::{+ extract::State,+ response::{IntoResponse, Json, Response},+};+use documents_hex::domain::create::{+ MarkdownSubtype, NewDocumentMetadata, NewMarkdownTextDocument,+};+use favorites::domain::ports::FavoritesService;+use model::response::{ErrorResponse, GenericSuccessResponse};+use model_entity::EntityType;+use model_user::axum_extractor::MacroUserExtractor;+use reqwest::StatusCode;++const HOW_TO_GUIDE_NAME: &str = "Macro how to guide";+const HOW_TO_GUIDE_TEMPLATE: &str = include_str!("./template/macro_how_to_guide.md");++/// Creates the "Macro how to guide" markdown document for the user and pins it+/// to their sidebar favorites. Called by the authentication service when a new+/// user signs up.+#[tracing::instrument(skip(state, user_context), fields(user_id=?user_context.macro_user_id))]+pub async fn handler(+ State(state): State<ApiContext>,+ user_context: MacroUserExtractor,+) -> Result<Response, Response> {+ tracing::info!("initialize how to guide");++ let created = state+ .documents_state+ .creator+ .create_markdown_text(+ user_context.macro_user_id.clone(),+ NewMarkdownTextDocument {+ metadata: NewDocumentMetadata::builder(HOW_TO_GUIDE_NAME).build(),+ markdown: HOW_TO_GUIDE_TEMPLATE.to_string(),+ subtype: MarkdownSubtype::Note,+ },+ )+ .await+ .map_err(|e| {+ tracing::error!(error=?e, "failed to create how to guide document");+ (+ StatusCode::INTERNAL_SERVER_ERROR,+ Json(ErrorResponse {+ message: "failed to create how to guide document".into(),+ }),+ )+ .into_response()+ })?;++ state+ .favorites_service+ .add_favorite(+ &user_context.macro_user_id,+ &EntityType::Document.with_entity_str(created.document_id()),+ )+ .await+ .map_err(|e| {+ tracing::error!(error=?e, "failed to favorite how to guide document");+ (+ StatusCode::INTERNAL_SERVER_ERROR,+ Json(ErrorResponse {+ message: "failed to favorite how to guide document".into(),+ }),+ )+ .into_response()+ })?;++ Ok((StatusCode::OK, Json(GenericSuccessResponse::default())).into_response())+}diff --git a/rust/cloud-storage/document_storage_service/src/api/documents/mod.rs b/rust/cloud-storage/document_storage_service/src/api/documents/mod.rsindex 2c98193bdd..132643c4fa 100644--- a/rust/cloud-storage/document_storage_service/src/api/documents/mod.rs+++ b/rust/cloud-storage/document_storage_service/src/api/documents/mod.rs@@ -21,6 +21,7 @@ pub(in crate::api) mod get_document_views;pub(in crate::api) mod get_documents_metadata;pub(in crate::api) mod get_full_pdf_modification_data;pub(in crate::api) mod get_user_documents;+pub(in crate::api) mod initialize_how_to_guide;pub(in crate::api) mod initialize_user_documents;pub(in crate::api) mod job_processing_result;pub(in crate::api) mod list_documents_with_access;diff --git a/rust/cloud-storage/document_storage_service/src/api/documents/template/macro_how_to_guide.md b/rust/cloud-storage/document_storage_service/src/api/documents/template/macro_how_to_guide.mdnew file mode 100644index 0000000000..604a447384--- /dev/null+++ b/rust/cloud-storage/document_storage_service/src/api/documents/template/macro_how_to_guide.md@@ -0,0 +1,110 @@+# Welcome to Macro 👋++Macro is one extremely fast, unified interface for all your work — email, messages, tasks, docs, and AI agents, all linked together in one database. This guide walks you through the essentials so you can hit the ground running.++> **Tip:** Keep this doc handy — it's pinned to your favorites in the sidebar. For the full documentation, visit [docs.macro.com](https://docs.macro.com).++---++## 1. Learn the five shortcuts that matter++Macro is built to be driven from the keyboard. These five will get you 90% of the way:++- `c` — create anything (then `d` for a doc, `t` for a task, `e` for an email, `m` for a channel, `a` for an AI chat)+- `cmd+k` — jump to anything by name+- `/` — search everything in your workspace+- `j` / `k` — move down / up in any list+- `e` — mark done and move on++The full list lives in the [keyboard shortcuts reference](https://docs.macro.com/keyboard-shortcuts).++## 2. Connect your email++Macro is a full email client that syncs with Gmail and Google Workspace — no migration needed. Connect one or more accounts in **Settings**, and every message lands in a single unified inbox. When you compose, you pick which address sends.++++Learn more in the [email docs](https://docs.macro.com/product/email).++## 3. Triage from one inbox++Press `g` then `i` to open your unified inbox: emails, channel messages, task assignments, doc mentions, and agent results — all in one list.++- **Signal** is what needs your attention. **Noise** is everything else (newsletters, promos), filtered by AI.+- Move with `j`/`k`, preview with `space`, open with `enter`, and clear items with `e` to get to inbox zero.++++Learn more in the [inbox docs](https://docs.macro.com/product/inbox).++## 4. Write docs (like this one!)++Press `c` then `d` to create a document. Docs are markdown-native and collaborative in real time — multiple people can type on the same line without conflicts.++- Type `/` to insert blocks: headings, tables, code, images, math, and more.+- Markdown autoformatting just works: `#` for headings, `-` for lists, `[]` for checklists, `>` for quotes.+- Select text to comment; comments with @mentions always notify.+- Full version history with time-travel browsing is built in.++++Learn more in the [docs documentation](https://docs.macro.com/product/docs).++## 5. Link everything with @mentions++The `@` key is Macro's superpower. In any doc, message, task, or email you can mention people, documents, tasks, files, emails, channels, and dates. Every mention is a **bidirectional link** — you can always trace back who referenced what, from where.++Learn more about [mentions](https://docs.macro.com/concepts/mentions) and [blocks](https://docs.macro.com/concepts/blocks).++## 6. Collaborate in channels++Press `c` then `m` to create a channel — a hub for team conversations with threads, reactions, and rich formatting. Add people by email; even folks without a Macro account get notified. Sharing follows mentions, so permissions take care of themselves.++++Learn more in the [channels docs](https://docs.macro.com/product/channels).++## 7. Track work with tasks++Press `c` then `t` to create a task. Tasks stay simple — status, priority, assignee — and you can turn any message or email into a task by hovering over it. With the [GitHub integration](https://docs.macro.com/integrations/github), tasks move to In Progress, In Review, and Done automatically as branches and pull requests advance.++++Learn more in the [tasks docs](https://docs.macro.com/product/tasks).++## 8. Put agents to work++Press `c` then `a` to chat with an agent, or mention **@Macro** in any channel. Agents see your whole workspace — docs, emails, messages, call transcripts — so they can summarize discussions, answer questions, draft documents, and create tasks. You can also schedule **automations** (daily reminders, weekly summaries) that deliver results straight to your inbox.++++Learn more in the [agents docs](https://docs.macro.com/product/agents).++## 9. Find anything, instantly++Press `/` and start typing — Macro searches docs, emails, messages, call transcripts, and file contents in under 50 milliseconds. Use quotes for exact matches, filter by type in the top-right, and preview results with `l`.++++Learn more in the [search docs](https://docs.macro.com/product/search).++## 10. Work side by side++Macro has a built-in window manager:++- `cmd+\` — split your workspace+- `shift+enter` — open anything in a new split+- `shift+h` / `shift+l` — move focus between splits+- `shift+esc` — maximize the focused split++---++## Where to go next++- [Getting started guide](https://docs.macro.com/getting-started) — the full onboarding walkthrough+- [Switching to Macro](https://docs.macro.com/switch-to-macro) — bring your team over+- [Keyboard shortcuts](https://docs.macro.com/keyboard-shortcuts) — the complete reference+- [FAQ](https://docs.macro.com/faq) — common questions+- [Connect AI clients via MCP](https://docs.macro.com/AI/mcp/overview) — use Macro from Claude and other agents++Welcome aboard — we're glad you're here. 🚀diff --git a/rust/cloud-storage/document_storage_service/src/api/internal/mod.rs b/rust/cloud-storage/document_storage_service/src/api/internal/mod.rsindex f49fa1c96a..35d3fc7115 100644--- a/rust/cloud-storage/document_storage_service/src/api/internal/mod.rs+++ b/rust/cloud-storage/document_storage_service/src/api/internal/mod.rs@@ -9,7 +9,8 @@ use super::{documents::save_document, history::delete_history};use super::{documents::{get_document, get_document_key, get_document_permissions, get_document_text,- get_full_pdf_modification_data, list_documents_with_access, location, put_document_update,+ get_full_pdf_modification_data, initialize_how_to_guide, list_documents_with_access,+ location, put_document_update,},user::populate_items,};@@ -101,6 +102,10 @@ pub fn router(state: ApiContext) -> Router<ApiContext> {>,),)+ .route(+ "/documents/initialize_how_to_guide",+ post(initialize_how_to_guide::handler).layer(ensure_user_exists_middleware.clone()),+ ).route("/documents/list_with_access",get(list_documents_with_access::list_documents_with_access_handler),diff --git a/rust/cloud-storage/document_storage_service/src/main.rs b/rust/cloud-storage/document_storage_service/src/main.rsindex 5961c3e2e3..ea6d74e2ae 100644--- a/rust/cloud-storage/document_storage_service/src/main.rs+++ b/rust/cloud-storage/document_storage_service/src/main.rs@@ -695,9 +695,10 @@ async fn main() -> anyhow::Result<()> {service::soup_favorites_reader::DssSoupFavoritesReader(favorites_service.clone()),)),favorites_state: FavoritesRouterState::new(- favorites_service,+ favorites_service.clone(),entity_access_service.clone(),),+ favorites_service,#[cfg(feature = "graphql")]graphql_soup_schema: graphql_soup::build_schema_from_arc(soup_service),#[cfg(feature = "graphql")]diff --git a/rust/cloud-storage/document_storage_service_client/src/document.rs b/rust/cloud-storage/document_storage_service_client/src/document.rsindex cb61fa7de1..5b26fc92eb 100644--- a/rust/cloud-storage/document_storage_service_client/src/document.rs+++ b/rust/cloud-storage/document_storage_service_client/src/document.rs@@ -384,6 +384,35 @@ impl DocumentStorageServiceClient {Ok(response_data)}+ /// Create the "Macro how to guide" onboarding document for a user and pin+ /// it to their sidebar favorites+ #[tracing::instrument(skip(self))]+ pub async fn initialize_how_to_guide(&self, user_id: &str) -> Result<()> {+ let url = format!("{}/internal/documents/initialize_how_to_guide", self.url);++ let res = self+ .client+ .post(&url)+ .header(MACRO_INTERNAL_USER_ID_HEADER_KEY, user_id)+ .send()+ .await?;++ let status_code = res.status();++ if !status_code.is_success() {+ let body = res.text().await.unwrap_or("no body".to_string());+ tracing::error!(+ body=%body,+ status=%status_code,+ user_id=%user_id,+ "error when initializing how to guide"+ );+ anyhow::bail!("HTTP {}: {}", status_code, body);+ }++ Ok(())+ }+/// Create a document#[tracing::instrument(skip(self))]pub async fn create_document_internal(