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.

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.rs
index 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 silently
diff --git a/rust/cloud-storage/document_storage_service/src/api/context.rs b/rust/cloud-storage/document_storage_service/src/api/context.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.md
new file mode 100644
index 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.
+
+![Signal and Noise filtering in the email inbox](https://mintcdn.com/macro-a2d84caa/Ii97L_qggyKuCmfd/images/email_signal_ss-2.png?w=1650&fit=max&auto=format&n=Ii97L_qggyKuCmfd&q=85&s=b2a7a335b727837212d5f706ab08576a)
+
+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.
+
+![The unified inbox](https://mintcdn.com/macro-a2d84caa/Ii97L_qggyKuCmfd/images/inbox_full.png?w=1650&fit=max&auto=format&n=Ii97L_qggyKuCmfd&q=85&s=5de630c86f1e929ad7b48443fb23ac3f)
+
+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.
+
+![The document editor](https://mintcdn.com/macro-a2d84caa/g-jFam3ihlnP-Mh7/images/Screenshot-2026-06-11-at-5.13.34-PM.png?w=1650&fit=max&auto=format&n=g-jFam3ihlnP-Mh7&q=85&s=c351d46cc5dc5a1366fd38a5ac4db38e)
+
+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.
+
+![A channel conversation](https://mintcdn.com/macro-a2d84caa/Ii97L_qggyKuCmfd/images/channels_screenshot.png?w=1650&fit=max&auto=format&n=Ii97L_qggyKuCmfd&q=85&s=84434dad5a10c37f63a05e470277dd32)
+
+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.
+
+![Creating a task from a message](https://mintcdn.com/macro-a2d84caa/Ii97L_qggyKuCmfd/images/task_from_message.png?w=1650&fit=max&auto=format&n=Ii97L_qggyKuCmfd&q=85&s=5fa12f9267181d2d55ad975e3a5249d4)
+
+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.
+
+![Chatting with an agent](https://mintcdn.com/macro-a2d84caa/Ii97L_qggyKuCmfd/images/agents_screenshot-1.png?w=1650&fit=max&auto=format&n=Ii97L_qggyKuCmfd&q=85&s=4e245bc1c0b478a004f5efeb5357276f)
+
+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`.
+
+![Unified search](https://mintcdn.com/macro-a2d84caa/Ii97L_qggyKuCmfd/images/search_screenshot-1.png?w=1650&fit=max&auto=format&n=Ii97L_qggyKuCmfd&q=85&s=c2ce481e88f6f74293d2134799d6ee71)
+
+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.rs
index 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.rs
index 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.rs
index 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(