doc(design): plan the website template deep-link flow#5422
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
@coderabbitai review |
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughA new design proposal documents a frontend-only v1 flow for preserving website template selections through authentication and consuming them in the appropriate cloud app first-run surface. It defines scope, edge cases, implementation steps, analytics, and test coverage. ChangesWebsite template deep-link
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
✅ Action performedReview finished.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: c98fb80f-8ac7-43cb-90d4-c3c8277b3e42
📒 Files selected for processing (2)
docs/design/website-templates-deeplink/README.mddocs/design/website-templates-deeplink/plan.md
| Each decision lists the options and the reason for the recommendation. These are the only real | ||
| choices in version 1; the rest is careful wiring. | ||
|
|
||
| ### Decision 1: which list of templates is the source of truth for keys |
There was a problem hiding this comment.
Let's simply go with the one that exists right now.
There was a problem hiding this comment.
Recorded as decided in Decision 1: the existing app registry (templates.ts) is the source of truth for keys in version 1, with no backend catalog work. See the "Decided:" line at the top of Decision 1.
| run before it runs, and a brand-new account does not spend model tokens before the person has | ||
| done anything. | ||
|
|
||
| Recommendation: for visitors arriving from the website, show the prompt behind a Start button and |
There was a problem hiding this comment.
Recorded as decided in Decision 2: website arrivals show the prompt behind a Start button, staged through the non-auto-send first-run seed state, which is what most in-app template paths already do.
| backend work this version is not doing. | ||
|
|
||
| Recommendation: cloud only for version 1. If we want to help self-hosters, the honest option today | ||
| is a visible "copy the prompt" action on the website card, because the website currently only |
There was a problem hiding this comment.
All right, let's do it in the cloud only for the moment, since this is not the marketplace yet. Let's just make sure we think about how we would do it outside of the cloud, right? Self-housing in the future, so that the architecture would allow that at some point, but let's not add copy, the promoter, or anything. Just get started, recall how today
There was a problem hiding this comment.
Recorded as decided in Decision 3: cloud only, and I removed the copy-the-prompt affordance entirely. I added a "How self-hosted would slot in later" note: the design keeps the key as the only value crossing the boundary and keeps the consume path reading a template source by key, so the version 2 backend "get template by key" endpoint lets a self-hosted path slot in without undoing any version 1 decision.
| screen that creates the agent from the template and then lands them in the playground, skipping | ||
| the normal onboarding for that one case. | ||
|
|
||
| Recommendation: the shared-consume approach, because it reuses each surface's existing |
There was a problem hiding this comment.
I'm honestly alright with both solutions. Just make sure it's something that the staff engineer won't criticize. It's kind of built using best practices, and obviously also take into account reusing stuff if there is something already there. Reusing it also makes sense, and finally take into account the fact that you have U.S. and E.U. clouds, so that should work in both cases.
There was a problem hiding this comment.
Recorded as decided in Decision 4: shared-consume. The section now spells out the staff-engineer rationale (maximal reuse of each surface existing useCreateAgent path, and it keeps template logic out of the post-login routing) and the United States and European cloud reasoning: the pending key lives in localStorage and the region redirect preserves the query string, so capture re-runs on the regional host and the consume happens where the user actually lands. It reuses the existing invite-flow technique rather than inventing a new one.
9ff3a72 to
56a54f4
Compare
1 participant
What this is
This is a design-only pull request. It adds a planning document and nothing else. No product code changes, no backend, no API. It is waiting for Mahmoud's review and a decision on four questions before anyone builds it.
The problem it plans for
The marketing website (the new
website/Astro project) shows agent template cards. Every "Use this template" button links to the bare addresshttps://cloud.agenta.ai/, so when a visitor clicks one, the app opens on its normal home page and has no idea which template the visitor picked. We want the click to carry the choice into the app, survive signup if the visitor has no account, and end with the app creating an agent from that template's prompt. Later this grows into a template marketplace.What the plan proposes
Version 1 is frontend only. The website adds a template key to each card's link (
?template=<key>). The app captures that key on arrival into local storage, reusing the exact technique the existing workspace-invite flow uses to survive a full signup, and then creates the agent once the user has a workspace and a project. It deliberately does not use the app'sredirectToPathparameter, which looks built for this but is captured and then discarded.One repo fact shapes the whole design. A brand-new user who just signed up does not land on the agent home page. By default the app sends first-time users to a native onboarding playground instead. So the plan consumes the template at whichever first-run surface the user actually reaches, not on a single page.
The decisions it asks for
How to read it
docs/design/website-templates-deeplink/README.mdis the index and glossary. Start here.docs/design/website-templates-deeplink/plan.mdis the full plan: current state, work in flight next to it, the four decisions with a reason for each, a tightly scoped version 1, an out-of-scope version 2 direction, a step-by-step build outline with file paths, the edge cases the consume step must handle, and a test plan.Notes
The plan was reviewed independently by Codex at high reasoning before this pull request. That review corrected the landing-surface behavior for new users and added the readiness, idempotency, region-redirect, and continuous-integration requirements now in the plan.
This is design only. Please do not merge to ship code. Merge only signals the plan is approved.
https://claude.ai/code/session_013Qe1Vf2yvj33BVd5W1q7HB