From 04bbda9be98c2c2741612de4fa5f8e528b614c7d Mon Sep 17 00:00:00 2001
From: Naiyuan Qing <145280634+NevilleQingNY@users.noreply.github.com>
Date: Fri, 24 Apr 2026 14:00:04 +0800
Subject: [PATCH] feat(onboarding): link to docs from key steps and starter
 tasks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Users who want to dig deeper now have a next hop from inside the flow
instead of having to dig through the help menu. Placed as secondary
links (muted, underline-offset-4) so they don't pull focus from the
primary CTA on each step.

Placement — one link per surface, placed in secondary regions:
- Welcome: "Learn how Multica works" below the subhead
- Questionnaire: "Learn how agents work" in the Why-we-ask aside
- Runtime aside (shared by desktop + web): "Learn about runtimes"
- Agent step: "Creating your first agent" in the About-agents aside
- StarterContentPrompt dialog: "Learn how Multica works"

Starter tasks (content/starter-content-templates.ts): added a single
"Learn about X" tail link per task, only on first occurrence of each
concept within a branch. 8 links on the agent-guided branch + 8 on
the self-serve branch + 1 on the welcome issue header (17 total).

URL scheme: absolute https://multica.ai/docs/{slug} throughout —
absolute so desktop (Electron) opens them in the system browser, and
the /en prefix is omitted because the docs middleware redirects it
away (English is the default, Chinese is /zh/).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../components/runtime-aside-panel.tsx        |  9 +++++
 .../components/starter-content-prompt.tsx     |  9 +++++
 .../views/onboarding/steps/step-agent.tsx     |  9 +++++
 .../onboarding/steps/step-questionnaire.tsx   |  9 +++++
 .../views/onboarding/steps/step-welcome.tsx   |  8 +++++
 .../utils/starter-content-templates.ts        | 34 +++++++++++++++++++
 6 files changed, 78 insertions(+)

diff --git a/packages/views/onboarding/components/runtime-aside-panel.tsx b/packages/views/onboarding/components/runtime-aside-panel.tsx
index fdb8c2239..4f82f09ee 100644
--- a/packages/views/onboarding/components/runtime-aside-panel.tsx
+++ b/packages/views/onboarding/components/runtime-aside-panel.tsx
@@ -38,6 +38,15 @@ export function RuntimeAsidePanel() {
           />
         </div>
       </section>
+
+      <a
+        href="https://multica.ai/docs/daemon-runtimes"
+        target="_blank"
+        rel="noopener noreferrer"
+        className="self-start text-[13px] text-muted-foreground underline underline-offset-4 transition-colors hover:text-foreground"
+      >
+        Learn about runtimes →
+      </a>
     </div>
   );
 }
diff --git a/packages/views/onboarding/components/starter-content-prompt.tsx b/packages/views/onboarding/components/starter-content-prompt.tsx
index 026b5c8ad..372462ccf 100644
--- a/packages/views/onboarding/components/starter-content-prompt.tsx
+++ b/packages/views/onboarding/components/starter-content-prompt.tsx
@@ -144,6 +144,15 @@ export function StarterContentPrompt() {
           </DialogDescription>
         </DialogHeader>
 
+        <a
+          href="https://multica.ai/docs/how-multica-works"
+          target="_blank"
+          rel="noopener noreferrer"
+          className="-mt-1 self-start text-[13px] text-muted-foreground underline underline-offset-4 transition-colors hover:text-foreground"
+        >
+          Learn how Multica works →
+        </a>
+
         <DialogFooter className="mt-2 gap-2 sm:justify-end">
           <Button
             variant="ghost"
diff --git a/packages/views/onboarding/steps/step-agent.tsx b/packages/views/onboarding/steps/step-agent.tsx
index 01b1cb3e6..12dd47b57 100644
--- a/packages/views/onboarding/steps/step-agent.tsx
+++ b/packages/views/onboarding/steps/step-agent.tsx
@@ -327,6 +327,15 @@ function AboutAgentsSide() {
         Add more agents anytime. A small team of specialized agents beats
         one jack-of-all-trades.
       </p>
+
+      <a
+        href="https://multica.ai/docs/agents-create"
+        target="_blank"
+        rel="noopener noreferrer"
+        className="self-start text-[13px] text-muted-foreground underline underline-offset-4 transition-colors hover:text-foreground"
+      >
+        Creating your first agent →
+      </a>
     </div>
   );
 }
diff --git a/packages/views/onboarding/steps/step-questionnaire.tsx b/packages/views/onboarding/steps/step-questionnaire.tsx
index 5983ff8c0..5b4be7d1d 100644
--- a/packages/views/onboarding/steps/step-questionnaire.tsx
+++ b/packages/views/onboarding/steps/step-questionnaire.tsx
@@ -328,6 +328,15 @@ function WhyWeAsk() {
           />
         </div>
       </section>
+
+      <a
+        href="https://multica.ai/docs/agents"
+        target="_blank"
+        rel="noopener noreferrer"
+        className="self-start text-[13px] text-muted-foreground underline underline-offset-4 transition-colors hover:text-foreground"
+      >
+        Learn how agents work →
+      </a>
     </div>
   );
 }
diff --git a/packages/views/onboarding/steps/step-welcome.tsx b/packages/views/onboarding/steps/step-welcome.tsx
index 6df3dd102..2e9d4121f 100644
--- a/packages/views/onboarding/steps/step-welcome.tsx
+++ b/packages/views/onboarding/steps/step-welcome.tsx
@@ -104,6 +104,14 @@ export function StepWelcome({
                   "By the end, a real agent will be replying to your first issue."
                 )}
               </p>
+              <a
+                href="https://multica.ai/docs/how-multica-works"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="self-start text-sm text-muted-foreground underline underline-offset-4 transition-colors hover:text-foreground"
+              >
+                Learn how Multica works →
+              </a>
             </div>
 
             <div className="flex flex-wrap items-center gap-3">
diff --git a/packages/views/onboarding/utils/starter-content-templates.ts b/packages/views/onboarding/utils/starter-content-templates.ts
index bf5633ceb..febf8094e 100644
--- a/packages/views/onboarding/utils/starter-content-templates.ts
+++ b/packages/views/onboarding/utils/starter-content-templates.ts
@@ -42,6 +42,8 @@ export function buildWelcomeIssueText(
     ``,
     `This is your workspace's first issue. Below, your agent will reply in a moment — that's how work happens here: you write what you want, your agent (or a teammate) picks it up and replies in the comments.`,
     ``,
+    `→ [Learn how Multica works](https://multica.ai/docs/how-multica-works)`,
+    ``,
     `---`,
     ``,
   ].join("\n");
@@ -139,6 +141,8 @@ export function buildAgentGuidedSubIssues(
         `**⚠️ Gotcha**: new issues default to Backlog. Agents pause on backlog. A hint dialog will pop up the first time — it's telling you "flip to Todo to start".`,
         ``,
         `**You'll know it worked when**: the Live card shows your agent thinking, and the Status flips to **In Progress** automatically.`,
+        ``,
+        `→ [Learn about assigning issues](https://multica.ai/docs/assigning-issues)`,
       ].join("\n"),
     },
     {
@@ -160,6 +164,8 @@ export function buildAgentGuidedSubIssues(
         `**Bonus — @mention an agent inside a comment**: on any issue, scroll to the comment box at the bottom. Type \`@\` and a dropdown appears listing members, agents, and other issues. Pick an agent → write your question → send. The mentioned agent replies in the comments.`,
         ``,
         `**You'll know it worked when**: the agent replies in the chat panel (or comment thread) within a few seconds.`,
+        ``,
+        `→ [Learn about chat](https://multica.ai/docs/chat)`,
       ].join("\n"),
     },
     {
@@ -187,6 +193,8 @@ export function buildAgentGuidedSubIssues(
         `Click **Save**.`,
         ``,
         `**You'll know it worked when**: the next task you assign to an agent picks up details from this context without you explaining again.`,
+        ``,
+        `→ [Learn about workspaces](https://multica.ai/docs/workspaces)`,
       ].join("\n"),
     },
   ];
@@ -211,6 +219,8 @@ export function buildAgentGuidedSubIssues(
         `5. Click **Send invite**`,
         ``,
         `They'll receive an email with a join link. Pending invites show in the collapsible "Pending Invitations" section below the member list — you can revoke from there.`,
+        ``,
+        `→ [Learn about members and roles](https://multica.ai/docs/members-roles)`,
       ].join("\n"),
     });
   }
@@ -259,6 +269,8 @@ export function buildAgentGuidedSubIssues(
       `4. Click **Create**`,
       ``,
       `**You'll know it worked when**: the new agent appears in the Assignee dropdown on any issue, and shows up in the left list on the Agents page.`,
+      ``,
+      `→ [Learn about creating agents](https://multica.ai/docs/agents-create)`,
     ].join("\n"),
   });
 
@@ -305,6 +317,8 @@ export function buildAgentGuidedSubIssues(
         `After the run finishes, the **Task Run History** below the card lists every past run. Click **View transcript** on any row to open the full interactive transcript — a timeline of every message, thinking step, tool call, and result.`,
         ``,
         `**Try it next time you assign an agent**: keep the issue open and watch the Live card appear below the description.`,
+        ``,
+        `→ [Learn about tasks](https://multica.ai/docs/tasks)`,
       ].join("\n"),
     },
     {
@@ -324,6 +338,8 @@ export function buildAgentGuidedSubIssues(
         `- Top-right dropdown: **Mark all as read / Archive all / Archive all read / Archive completed** for bulk cleanup`,
         ``,
         `**Tip**: "Archive completed" is the fastest way to clear the noise from issues already finished.`,
+        ``,
+        `→ [Learn about the inbox](https://multica.ai/docs/inbox)`,
       ].join("\n"),
     },
     {
@@ -342,6 +358,8 @@ export function buildAgentGuidedSubIssues(
         `5. Click **Create**`,
         ``,
         `**Good first autopilots**: daily digest of GitHub activity, weekly "what's blocked" check, or a Monday-morning triage of any issues still in Backlog.`,
+        ``,
+        `→ [Learn about autopilots](https://multica.ai/docs/autopilots)`,
       ].join("\n"),
     },
   ];
@@ -383,6 +401,8 @@ export function buildSelfServeSubIssues(
         `   The daemon keeps running after you close the terminal — you don't have to leave anything open.`,
         ``,
         `**Verify**: sidebar → bottom **Configure** section → **Runtimes** → you should see at least one connected runtime.`,
+        ``,
+        `→ [Learn about runtimes](https://multica.ai/docs/daemon-runtimes)`,
       ].join("\n"),
     },
     {
@@ -406,6 +426,8 @@ export function buildSelfServeSubIssues(
         `**Note**: an agent is just an LLM + instructions + workspace access. Nothing locks a "Coding Agent" to coding — same agent can do research, writing, planning. Keep it flexible.`,
         ``,
         `**You'll know it worked when**: the new agent appears in the Assignee dropdown on any issue.`,
+        ``,
+        `→ [Learn about creating agents](https://multica.ai/docs/agents-create)`,
       ].join("\n"),
     },
   ];
@@ -433,6 +455,8 @@ export function buildSelfServeSubIssues(
         `5. Watch the agent reply in the comments and a **Live card** appear in Activity`,
         ``,
         `**⚠️ Gotcha**: new issues default to **Backlog**. You must flip to **Todo** to trigger the agent.`,
+        ``,
+        `→ [Learn about assigning issues](https://multica.ai/docs/assigning-issues)`,
       ].join("\n"),
     },
     {
@@ -457,6 +481,8 @@ export function buildSelfServeSubIssues(
         `Click **Save**.`,
         ``,
         `**You'll know it worked when**: the next task you assign to an agent picks up details from this context without you explaining again.`,
+        ``,
+        `→ [Learn about workspaces](https://multica.ai/docs/workspaces)`,
       ].join("\n"),
     },
   ];
@@ -481,6 +507,8 @@ export function buildSelfServeSubIssues(
         `3. Type a question → press **Enter**`,
         ``,
         `**Bonus**: inside any issue's comment box, type \`@\` to mention an agent or member.`,
+        ``,
+        `→ [Learn about chat](https://multica.ai/docs/chat)`,
       ].join("\n"),
     },
   ];
@@ -517,6 +545,8 @@ export function buildSelfServeSubIssues(
         `1. Sidebar → **Settings** (⚙️, bottom)`,
         `2. Left tab list → **Members** (people icon)`,
         `3. Click **Add member** → enter email → pick role → **Send invite**`,
+        ``,
+        `→ [Learn about members and roles](https://multica.ai/docs/members-roles)`,
       ].join("\n"),
     });
   }
@@ -552,6 +582,8 @@ export function buildSelfServeSubIssues(
         `When an agent is working on an issue, a **Live card** appears at the top of the **Activity** section (it sticks to the top of the viewport as you scroll).`,
         ``,
         `It shows in real time which tool the agent is calling, streaming thoughts, and current status. After the run finishes, the **Task Run History** below the card lists every past run — click **View transcript** to open the full timeline.`,
+        ``,
+        `→ [Learn about tasks](https://multica.ai/docs/tasks)`,
       ].join("\n"),
     },
     {
@@ -568,6 +600,8 @@ export function buildSelfServeSubIssues(
         `1. Sidebar → under **Workspace** group → click **Autopilot** (⚡ Zap icon)`,
         `2. Pick one of 6 templates, or click **+ New autopilot** top-right`,
         `3. Fill: **Name** / **Prompt** / **Agent** / **Schedule** (frequency + time + timezone) → **Create**`,
+        ``,
+        `→ [Learn about autopilots](https://multica.ai/docs/autopilots)`,
       ].join("\n"),
     },
   );