First-use surfaces
The product site, documentation, catalog and World console form one route from a person's task to a working World. Each surface owns a different decision. The documentation map owns page navigation; this page owns the first-use design references and the journeys those pages must make possible. The model owns the state vocabulary.
References and their application
These are design decisions drawn from the linked products, not a claim that World implements their features or that a comparison proves a journey works.
| Surface | Reference | Practice to follow in World |
|---|---|---|
| Product introduction | LocalStack introduction, Neon introduction | Explain the outcome and the existing tools the person keeps before introducing implementation vocabulary. Show a real product view whose capabilities match the selected release. Give one local starting action and separate complete examples for people who already know their task. |
| Documentation entry | LocalStack getting started, Docker documentation | Separate learning, adopting an existing app, finding a complete example and looking up a command. Prerequisites and the account boundary appear before installation. A task ends with useful next tasks rather than an unrelated page-order suggestion. |
| AI tool workflow | OpenAI function calling, OpenAI streaming | Keep the model turn, application tool execution and returned tool result distinct. Show a complete SDK conversation, read the tool's actual stored effect and consume the streamed final answer. A scripted choice exercises the application without establishing model judgment. |
| Storage SDK example | Cloudflare R2 S3 client | Name endpoint, region and credential provenance before the client. Complete upload and read outcomes and show how retained data resumes; keep unexercised storage features separate. |
| Authentication SDK example | Clerk backend SDK | Show installation and normal client initialization before resource calls. Identify the backend workflow on the catalog card and release page before the reader opens the recipe. Separate stored session state from signed-token verification; name the credential source and the browser sign-in scope. |
| Rate-limit SDK example | Upstash rate-limit getting started | Explain credentials, SDK installation and client configuration before consuming a budget. Name the chosen algorithm and client pin, await pending work and distinguish quota decisions from application HTTP responses. |
| Library first use | Neon serverless driver | Explain local installation, runtime prerequisites and the working client before the full method reference. Keep transport configuration and lifecycle ownership visible, and link the concrete error path. |
| Managed database client | Supabase database connections | Distinguish a native SQL connection from HTTP data APIs before client setup. Show the returned row, retained readback and backing ownership; a database query does not establish the vendor's Auth or Storage scope. |
| Catalog discovery | Terraform registry, Docker Hub library | Make vendor, package and publisher searchable. Workflow terms come from release-specific examples. Keep the default choice visible, while making other publishers and versions accessible. A publisher badge describes its source, not API completeness. |
| Catalog release | Docker Hub tags, Terraform provider requirements | Preserve the selected package and exact version through README, setup and copy actions. Separate workflow documentation, installation, versions and evidence. An install box copies a complete command. A generic setup link remains about the selected release; a worked example names its vendor and scope. |
| World inspection | Console page references | Show records and before/after fields in the product's existing controls. Vendor screens appear only when declared. Infrastructure lifetime belongs in settings rather than the vendor Records list. |
| Customer mirror inspection | Stripe Customers, Stripe customer detail layout | Follow Customers to the SDK-created record. Read actual activity in the primary column and details/metadata on the right; missing records remain missing. |
| Workplace conversation mirror | Slack quick start | Use the familiar workspace rail, channel sidebar, message pane and thread to inspect the actual handoff. Sending a message or reply changes the same vendor records the SDK reads; administration remains a separate task. |
| Workplace issue mirror | Linear My Issues, Linear issue assignment | Navigate the workspace and team issue list, then read the issue with its description and properties sidebar. Each edit uses the existing vendor mutation and its actual refusal; OAuth consent is a separate flow. |
| Errors and returning use | LocalStack connection guides, Neon branching | Explain which state is retained and what the next action changes. Resume, reset, SDK routing, missing operations and platform access are different decisions. Do not make reinitialization or data deletion the default recovery. |
People and their jobs
Each row names an entry and a concrete result. Reaching a documentation page is not completion. Retained walkthrough evidence states which source, packages, mode and actions actually ran.
| Person or agent | Likely front door | Result they came for |
|---|---|---|
| Curious developer | Product page, getting started | Create and retrieve a customer with the real SDK, see its stored record, reset deliberately and stop. |
| App developer | Search result, catalog release, existing-app guide | Select only the app's required vendors, keep its SDKs and run its usual command with the chosen sources. |
| Coding-agent user | Product prompt, agent guide | Install the tools, review the agent's detected vendors and obtain the same app result and dashboard link. |
| Tool-using agent builder | Workplace example, AI recipe | Provide the agent's tools with related company data, inspect every stored effect, and resume a partially completed handoff. Scripted responses do not prove model reasoning. |
| AI integration developer | Model vendor catalog release, AI messages or tools example | Read and stream a labeled stub through the real SDK, author a known answer or tool call, execute the tool through its vendor SDK, read its stored result and inspect matcher outcomes. Choose a model from the twin's clock-filtered catalog. |
| Browser or QA developer | Browser guide, onboarding example | Submit the application's form and distinguish browser state, app database state and vendor records; rehearse refusal and retry. |
| Payment integration developer | Stripe catalog release, hosted Checkout recipe | Complete a hosted payment after a decline, start a subscription trial, manage billing in the portal and read each saved result through the real SDK. A redirect alone does not establish application fulfillment. |
| Backend developer | Catalog, database or email recipe | Use the real driver or SDK, read the stored result, resume retained data and understand the selected protocol's limits. |
| SQL app developer | Supabase catalog release, managed-database recipe | Receive a synthetic native connection, create and read an app row through node-postgres, stop and resume that same row, and distinguish native database behavior from the vendor's HTTP APIs. |
| Storage app developer | R2 catalog release, object-storage example | Select the actual storage vendor despite its cross-vendor SDK, upload a file, read its bytes and metadata, list it and resume retained data without another write. |
| Authentication backend developer | Clerk catalog release, authentication example | Create a user and session through the real SDK, verify the issued token, revoke the stored session and read the same state after resume without using a real account. |
| API quota developer | Upstash catalog release, rate-limit example | Store customer data, allow two requests, refuse the third, resume the exhausted budget and advance the clock into a renewed window without a real Redis account. |
| SDK toolchain author | SDK reference, Node control guide | Import the locally pinned World library, run the app through its World environment, read its changes, forward its exit code and stop owned compute without discarding state. |
| Python or native SDK user | Client-routing guide, selected vendor release | Configure the client's supported proxy and CA settings, keep its vendor SDK calls, create and retrieve actual twin records, and diagnose transport separately from unsupported operations. |
| CI maintainer | CI guide | Install locked dependencies, create independent worker state, run the app command and stop compute on each exit path. |
| Parallel-worker coordinator | Integration example | Preserve a baseline, isolate worker changes and land only selected changesets at the named integration destination. |
| Incident responder | Failure-reproduction guide | Preserve the failing starting point, seed, clock and handlers, make a correction, and give a teammate a reproducible handoff. |
| Invited teammate | Team-provided link, team onboarding | Identify the actual platform and World, obtain access, choose local history or shared execution deliberately, and see the teammate's result. |
| Returning developer | Saved app folder, resume guide | Resume the intended branch without resetting data, inspect what changed and stop without deleting it. |
| Founder or demonstrator | Complete example, demo guide | Present a visible business outcome, a refusal and a retry, then restore a known baseline for another presentation. |
| Operations user | Shared-World and deploy guides | Inspect a changeset's before/after result and distinguish a World push from a vendor deployment and its policy receipts. |
| Self-hosting operator | Hosting guide | Serve Worlds at a known URL and provide scoped access; documentation hosting is separate from a platform. |
| User choosing or updating a release | Catalog or update guide | Compare the actual operations and evidence, retain exact pins, trial a candidate separately and preserve existing state. |
| User with an unsupported vendor or client | Catalog empty result, routing or recovery guide | Identify the missing operation or routing requirement and choose a deliberate alternative without a fabricated success. |
| Independent publisher | Catalog contributor link | Use the catalog's publisher procedure from its own repository. Publishing a twin is separate from using a World. |
Presentation contracts
The product page explains why to use a World before explaining how twins are implemented. Its screenshots name what is actually visible; a sample image never promises every vendor has a corresponding screen. A complete example stays visible at the point a person chooses a task, and links to the canonical cookbook source.
Catalog workflow discovery uses curated exact-release example metadata. It can help someone
find onboarding, handoff or parallel-worker recipes without changing the catalog's admitted
releases or implying unmeasured operations. Only selectable releases receive runnable-example
links. Each example link names the recipe's own twin pin from its canonical manifest when it differs from the selected release, and links that retained release when available. Installation uses the starter cohort's exact pins and ./node_modules/.bin/volter from the app folder.
Captured assessment tool versions remain historical evidence rather than the current setup.
The primary example follows the vendor's focused task. A larger multi-vendor recipe stays
available as another use case. Retained publisher READMEs identify their source and historical
instructions; the selected release's Setup owns the primary installation action.
The workplace recipe's Slack browser walkthrough names its local synthetic sign-in and captured
mail. Its member administration screen does not stand in for a chat client; the ordinary SDK
read owns the handoff's ticket and notification outcomes. Updating that recipe's pins also
updates its exact-release discovery links, while preserving older releases and their evidence.
Catalog detail sections have shareable URLs. Back and Forward restore the section, and changing
the version in the picker preserves it, so comparing Setup or Evidence does not return the
person to Overview. README headings remain Overview links.
Direct vendor, package, publisher, description and example matches precede incidental README
matches; generic credential text must not bury the vendor whose workflow the person requested.
README matches remain available and can describe limitations rather than supported behavior.
Those matches use readable text and code, including link labels; hidden link destinations
must not make a search for GitHub return every README hosted there.
Documentation uses its framework's navigation and layout. Canonical page links own the next action; an unconditional footer does not send every finished task to resume or recovery. The generic catalog guide describes adopting the selected release. A vendor-specific tutorial is a separately named example. Both remain discoverable from the documentation map.