From 6d4bb1842b9473f5b556cdb1983074b1dfc3ae5c Mon Sep 17 00:00:00 2001 From: Catharine McNally Date: Thu, 22 Oct 2026 20:25:45 -0400 Subject: [PATCH 1/6] docs: clarify Replica onboarding paths Separate local prototyping, shared hosting, and joining an existing team. Clarify prerequisites and continuation steps, and update the README with product framing and a demo. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 045ed8e1-41ea-44f3-a2c6-d9f485f87ca1 --- README.md | 56 ++++-- docs/README.md | 8 +- docs/getting-started.md | 13 +- docs/local-prototyping.md | 178 ++++++++++++++++++++ docs/prototype-environment.md | 262 +++++++++++++++++++++-------- docs/prototype-repository-setup.md | 109 ++++++++---- hub/docs/deployment.md | 15 ++ 7 files changed, 508 insertions(+), 133 deletions(-) create mode 100644 docs/local-prototyping.md diff --git a/README.md b/README.md index 47fdfe3e..e2b44cbe 100644 --- a/README.md +++ b/README.md @@ -2,40 +2,49 @@ Replica

-# Replica: An open-source prototyping tool +# Replica: An open-source AI prototyping tool -Replica helps your entire product team prototype with your design system. It's an open-source tool that uses AI to turn ideas into interactive prototypes, guided by your components, patterns, and documentation. +Turn ideas into interactive prototypes using your own design system. Replica is an open-source, AI-powered prototyping tool created by GitHub Design for designers, product managers, and engineers. -Designers create and approve the guidance. People across design, product, and engineering can then describe a change in the GitHub Copilot app, try the result, and refine it with their team and users. +Designers define the guidance using your team's components, patterns, and documentation. Anyone on the product team can then use natural language in the GitHub Copilot app to create and refine prototypes that reflect how your product works. You can start locally without a server, domain, or Replica Hub. -Use prototypes to test assumptions and work through questions together. Your team still decides what should ship and how to build it. +## What can you do with Replica? -Replica is MIT-licensed. You can prototype locally without a server or set up Replica Hub for hosting and commenting. +- **Prototype with your design system:** Use your existing components, patterns, and approved guidance to shape AI-generated prototypes. +- **Turn ideas into interactive experiences:** Describe what you want to explore, then see, test, and refine the result beside your Copilot conversation. +- **Collaborate and gather feedback:** Publish prototypes to an optional Replica Hub hosted by your organization, where teammates can explore them and leave comments. +- **Adapt Replica to your team:** Customize the open-source tooling and guidance to fit your product and workflows. -## Try Replica +## See Replica in action -Explore Replica before setting anything up. +https://github.com/user-attachments/assets/36547180-aca9-43cc-8931-b538f0883885 -[Watch the Replica introduction on YouTube](https://www.youtube.com/watch?v=J2Z28CwIfsA) +
+Demo video music credits + +*Music: [“Electrodoodle”](https://incompetech.com/music/royalty-free/index.html?isrc=USUAN1200079) by Kevin MacLeod ([incompetech.com](http://incompetech.com/)), licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Excerpted, level-adjusted and faded for this video.* + +
+ +[Watch the Replica introduction on YouTube](https://www.youtube.com/watch?v=J2Z28CwIfsA). ## Get started with Replica -Replica has four parts: +You don't need to set up everything at once. Start with the guide that matches your next step: trying Replica locally, setting up hosting, or joining your team's existing repository and Hub. -| Part | What it does | +| Your goal | Start here | | --- | --- | -| **Starter** | Creates a local prototype project with agent skills and a working app you can adapt. | -| **Copilot canvas extension** | Opens your local prototype alongside your Copilot conversation. | -| **Replica Hub (optional)** | Hosts published prototypes so your team can try them and leave comments. | -| **GitHub build action** | Builds prototypes for publishing to Hub. It is not needed for local prototyping. | +| Start or continue prototyping locally | [Create your first local prototype](docs/local-prototyping.md). Use the starter or an existing prototype repository, add team guidance, and build something useful. No Hub required. | +| Set up hosting and comments for your team | [Set up shared hosting and team feedback](docs/prototype-environment.md). Check hosting needs early, build with your team's design guidance, and connect Hub when it is ready. | +| Join a team with a repository and Hub already in use | [Join your team's Replica environment](docs/getting-started.md). Use its existing setup to create, publish, and review a prototype. | -**Ready to make prototypes?** Follow [Get started with Replica](docs/getting-started.md) to install the GitHub Copilot app, add your team's prototyping repository, install the canvas, and create your first prototype. It also covers connecting to Hub, publishing, sharing and commenting, and adding controls. +If hosting is blocked, you can work locally and connect the same repository later. -**Creating a prototyping repository?** Point your agent at [prototype repository setup](docs/prototype-repository-setup.md). It covers new and existing repositories, getting the starter running locally, and continuing with product guidance or a shared team baseline. Local prototyping needs no Hub. +### What you need -**Setting up Replica for your organization?** Follow [environment setup](docs/prototype-environment.md) to add shared guidance and starting pages, deploy Hub, and connect publishing and team feedback. Your organization deploys and runs Hub on its own infrastructure. GitHub doesn't host it. +**Local prototyping** uses the [GitHub Copilot app](https://github.com/features/ai/github-app), Git, and Node.js with npm on macOS or Linux. Each walkthrough covers installation and the repository's requirements. -**How did setup go?** [Share your feedback](https://survey.alchemer.com/s3/9055055/Replica-feedback). It helps us make Replica easier to start. +**Hosted publishing and comments** also need a Linux server, a dedicated domain with wildcard DNS and HTTPS, network access, and GitHub permissions and approvals. The hosting guide starts with these checks. ### Copilot requirements @@ -44,6 +53,17 @@ Replica has four parts: - **Your own provider:** this option is in public preview and subject to change. The provider's costs and terms apply. - **Viewing and review:** viewing a finished prototype or reviewing it in Hub does not require a Copilot subscription. +## What's included + +| Part | What it does | +| --- | --- | +| **Starter** | Creates a local prototype project with skills for Copilot and a working app you can adapt. | +| **Replica plugin** | Adds the Replica canvas to Copilot, showing your running prototype beside your conversation. | +| **Replica Hub (optional)** | Hosts published prototypes so your team can try them and leave comments. | +| **GitHub build action** | Builds prototypes for publishing to Hub. It is not needed for local prototyping. | + +Agents creating or adapting repositories should follow [prototype repository setup](docs/prototype-repository-setup.md). + ## Data and privacy Your organization operates its Hub and controls its configuration. Hub records publishing and review activity in its own database and retains those activity events for 90 days. Exporting them to Segment, Mixpanel, or a custom HTTPS endpoint requires configuration by a repository administrator. Replica does not automatically send those activity records to GitHub. diff --git a/docs/README.md b/docs/README.md index 449de56f..c29a2a9a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,11 +4,13 @@ These guides apply across the Replica monorepo. Start with [Contributing](../CON ## Prototype guides -[Get started with Replica](getting-started.md) walks new users through installing Copilot, adding their team's repository and canvas, creating and publishing a prototype, sharing feedback, and adding controls. +[Create your first local prototype](local-prototyping.md) walks you through the starter and canvas without Hub, then adding approved team guidance and building a useful prototype. -[Set up a prototype repository](prototype-repository-setup.md) guides agents through new or existing repository targets, starter installation, the fresh-session handoff, and a verified local preview before optional product guidance or team setup. +[Set up shared hosting and team feedback](prototype-environment.md) starts with hosting requirements, then team guidance and a useful local prototype. Teams can arrange hosting alongside that work, then connect Hub, publish, and invite teammates. -[Set up and configure your prototype environment](prototype-environment.md) walks environment maintainers through creating the shared repository, adding design-system guidance and templates, deploying Hub with Docker, connecting builds, and inviting the team. +[Join your team's Replica environment](getting-started.md) walks authors through using an existing team repository and Hub, creating and publishing a prototype, sharing feedback, and adding controls. + +[Set up a prototype repository](prototype-repository-setup.md) is the supporting agent guide for new or existing repository targets, starter installation, session handoff, and verification. People following the walkthroughs above do not need to follow its agent instructions. ## Shared conventions diff --git a/docs/getting-started.md b/docs/getting-started.md index 650cb9fd..ed928e87 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,8 +1,8 @@ -# Get started with Replica +# Join your team's Replica environment Create an interactive prototype with GitHub Copilot, publish it to Replica Hub, and collect feedback from your team. This guide helps you join your organization's prototyping environment and create your first shared prototype. -You can create and try prototypes locally without Hub. To create a repository rather than join an existing one, follow [prototype repository setup](prototype-repository-setup.md). Publishing and team comments need a Hub hosted by your organization, a connected GitHub repository, and the repository's Replica build workflow. Ask your team for its Hub URL and repository, or follow [environment setup](prototype-environment.md) if you are setting up shared hosting for the first time. +Starting on your own? Follow [Create your first local prototype](local-prototyping.md), which needs no Hub. Setting up hosting for your organization? Follow [Set up shared hosting and team feedback](prototype-environment.md). Publishing and team comments need an organization-hosted Hub, a connected GitHub repository, and the repository's Replica build workflow. ## 1. Download the GitHub Copilot app @@ -35,7 +35,7 @@ Add the repository to the Copilot app: If the repository is missing or access is denied, ask its maintainer to check your GitHub access. See [connecting a repository in Copilot](https://docs.github.com/en/copilot/get-started/quickstart-copilot-app#connecting-a-repository-or-folder) for app setup help. -**Setting up the environment for your organization?** Follow [Set up and configure your prototype environment](prototype-environment.md) instead. It covers creating the repository, adding design-system guidance, deploying Hub with Docker, and connecting builds before inviting teammates. +**No shared environment yet?** Use the [hosted setup walkthrough](prototype-environment.md) to check hosting needs, add your team's guidance, and build a prototype while hosting is arranged. Connect Hub when it is ready, then publish and invite teammates. ## 3. Install and enable the canvas @@ -60,8 +60,9 @@ If the canvas is missing, check that installation completed and that you started ## 4. Create a prototype -Start a new prototype by clicking **+** button next to your prototype repository. Each prototpye should get it's own session. -Describe the change you want and let copilot work for a couple minutes. +Start a new prototype by clicking **+** next to your prototype repository. Give each prototype its own session. Before editing, ask Copilot to confirm that the session uses a new prototype branch, not the repository's default branch. + +Describe the change you want and let Copilot build it. ### Example prompt: Create a searchable project list @@ -87,7 +88,7 @@ Return to the canvas after approval. Connecting does not push or publish anythin If the connection fails, check the Hub URL and repository access with your team. An expired or revoked connection needs browser approval again. See [canvas connection guidance](../hub/docs/prototype-canvas.md#pairing-and-review) for more detail. -Administrators can follow [Hub and repository setup](prototype-environment.md#4-deploy-the-hub). +Administrators can follow [Hub and repository setup](prototype-environment.md#5-deploy-the-hub). ## 6. Publish your prototype diff --git a/docs/local-prototyping.md b/docs/local-prototyping.md new file mode 100644 index 00000000..770aa352 --- /dev/null +++ b/docs/local-prototyping.md @@ -0,0 +1,178 @@ +# Create your first local prototype + +This guide walks you through running a prototype locally, adding your team's design-system guidance, and building a useful first prototype. You can start from the Replica starter or use a prototype repository your team already maintains. + +You'll use the **Replica canvas**, a panel in the GitHub Copilot app that shows your running prototype beside your conversation. It is included in the Replica plugin. Step 3 below covers installing the plugin if needed and enabling the canvas. + +**You can prototype locally without Hub, Docker, a domain, or a GitHub repository.** You can also use a team repository already configured for local development while hosting is being arranged. Publishing and shared review comments need Hub, but local work does not. + +For a quick trial, stop after the app works in the canvas in step 4. Continue through steps 5 and 6 to build with your team's guidance. + +If your team already has a connected repository and Hub, follow [Join your team's Replica environment](getting-started.md). For the full team setup, including hosting, use [Set up shared hosting and team feedback](prototype-environment.md). + +## 1. Prepare your local development environment + +If you don't already have the [GitHub Copilot app](https://github.com/features/ai/github-app), install it and sign in. You also need [Git](https://git-scm.com/), [Node.js](https://nodejs.org/), and npm. Use a Node.js version matching `engines.node` in your repository's `package.json`, or [the starter's package.json](../starter/package.json) for a new repository. Reuse a compatible installation. + +The Replica canvas supports local previews on macOS and Linux. It uses `lsof` to find running local servers. Install missing tools through your organization's approved process. The starter installer does not install Node.js or change your shell configuration. + +Copilot requires GitHub sign-in, but creating the local starter does not require GitHub repository access. You can use a Copilot plan or [connect your own model provider](https://docs.github.com/en/copilot/how-tos/github-copilot-app/use-byok-models). + +## 2. Create or open your prototype repository + +With your local development environment ready, the next step is to open a prototype repository in Copilot. You can create one from the Replica starter or use a repository your team has already set up for local prototyping. + +If you already have a Replica repository, use **Open an existing repository** below. You do not need to copy the starter files or start again. + +### Create a repository from the starter + +The installer creates a new folder for your prototype, named `my-prototype` in the example below. Choose a name that is not already in use. + +In a terminal, go to the directory where you want the new folder created, then download the installer: + +```sh +curl -fLSs https://raw.githubusercontent.com/github/replica/main/scripts/install-starter.sh -o install-starter.sh +``` + +Review the installer, then run it with a name for your new project folder: + +```sh +bash install-starter.sh my-prototype +``` + +This creates `my-prototype` as an independent local Git repository. It does not create a GitHub repository, commit files, or publish anything. + +In the Copilot app, choose **Projects → + → Local folder or repository** and add the new folder. Before accepting its repository configuration, review `.github/github-app.yml` and the copied README. Session startup can install Copilot CLI globally if missing, install or enable the Replica plugin, and install app dependencies with `npm ci`. + +Start a fresh session in the new repository so Copilot can discover its included skills. If another session created the folder, give the new session a summary of completed setup and what you want to build. + +Continue at step 3. + +### Open an existing repository + +Choose the repository from **Projects** in Copilot. If it is not listed, choose **Projects → + → Local folder or repository** for a local copy, or **Projects → + → Add GitHub repository** to select your team's repository on GitHub. Start a session in that repository and review any setup configuration before accepting it. + +If the repository does not already use Replica, ask Copilot to inspect its instructions, app, and Git state before changing it. Agree whether to adapt the existing app or create a separate starter repository. Preserve the existing files, remote, and history. + +**Ready to continue:** the repository is open in Copilot. Opening it does not push changes or publish a prototype. + +Continue at step 3. + +## 3. Enable the Replica canvas + +With your repository open in Copilot, the next step is to enable the Replica canvas so you can preview the app beside your conversation. + +Check the session setup output for dependency or plugin failures. Successful dependency installation does not mean the canvas is enabled. + +### Install the plugin if needed + +If the Replica plugin appears under **Customize → Installed**, continue at [Activate the plugin and canvas](#activate-the-plugin-and-canvas) below. + +The Replica starter installs the plugin during session setup. It checks for Copilot CLI and installs it if missing. If setup failed, resolve the reported error, then run `node scripts/setup-replica-plugin.mjs` from the repository folder to retry plugin setup. + +For repositories without that setup script, use the manual plugin commands below. These require the `copilot` command in your terminal. Check with `copilot --version`; if the command is not found, follow the [Copilot CLI installation instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli) before continuing. + +These commands install Replica from its default branch. If your organization requires a specific version or source, use its installation instructions instead. + +First, add Replica's plugin marketplace if you haven't already: + +```sh +copilot plugin marketplace add github/replica +``` + +Then install the Replica plugin: + +```sh +copilot plugin install replica-prototype@replica +``` + +### Activate the plugin and canvas + +In the sidebar, open **Customize → Installed** and enable both the `replica-prototype` plugin and its canvas extension. They are separate switches. + +Start a fresh session after installation or enablement. Open **+ → Canvas → Replica prototype**. Keep only one copy of the Replica canvas enabled. + +If installation fails, use the error and recovery instructions in the terminal or session setup output. Resolve policy or permission errors through your organization's approval process rather than bypassing them. If the canvas is still missing, confirm both switches are enabled and start a fresh session after changing them. + +**Ready to continue:** the Replica canvas opens in your current session. You do not need to connect it to Hub. + +## 4. Run the app in the canvas + +With the canvas enabled, try the starter app or your team's existing prototype before making changes. The goal is to see it running and confirm that you can use it. + +Ask Copilot: + +```text +Run this repository's app locally and show it in the Replica canvas. +Use the run commands in its README and the URL printed by the server. +Do not change the app, connect to Hub, or publish anything yet. +``` + +If the canvas lists running servers, choose **Connect** beside your app's server. If none is running, choose **Start dev server**. + +Once the page appears, try its navigation and any included interactions. Check the preview itself rather than relying on a setup success message. + +If the page does not appear or reports an error, ask Copilot to investigate using the repository's README and, where present, `SETUP.md` before continuing. + +**Ready to continue:** the app works in the canvas. This is enough for a quick trial. Continue below to add team guidance and build a prototype. + +## 5. Add your team's guidance + +Now that you can try the app, give Copilot the information it needs to build prototypes that follow your team's product and design system. + +If the repository already uses your team's approved guidance, review what is in place and continue to step 6. You do not need to create it again. + +Otherwise, run `/setup-skills` in your Copilot conversation. Provide your product documentation, design-system documentation, and any component or token packages your team uses. Share only sources your organization permits you to use. + +Copilot checks those sources and drafts instructions for building prototypes. It asks for permission before installing any packages. + +Review the drafts using your team's usual approval process and request any corrections. Once the drafts are reviewed, give Copilot separate approval to apply them. Ask it to confirm which guidance is now in use. + +If a package cannot be installed or the app no longer runs, resolve the reported error before continuing. Without approved guidance, you can still explore the starter, but you have not yet checked whether Replica follows your team's design system. + +**Ready to continue:** the reviewed guidance is in use and the app still runs. The next step is to try that guidance in a prototype. + +## 6. Build one useful prototype + +With the app running and your team's guidance in place, choose one small task you want to explore. Describe what someone should be able to do, then ask Copilot to build it. For example: + +```text +Build a searchable project list using our approved design-system guidance +and sample data. Include an empty result state and a way to clear the search. +Keep it separate from our live product. Show it in the Replica canvas. +Before editing, check that the reviewed app and guidance are committed. +If this is a new repository with no commits, ask for my approval to save +that starting version in a local commit on its initial branch. +Use a separate branch for this prototype. Leave the default branch unchanged. +Ask for approval before making any commits. Do not push or publish anything. +``` + +The prompt asks Copilot to preserve a reusable starting version before experimenting. A new starter needs its first local commit before a separate prototype branch can keep those versions apart. Copilot must ask for your approval to make that commit; it does not upload or publish anything. For an existing team repository, use its usual review process for changes to the shared starting point. + +Try the result in the canvas. For the example above, search for a project, try a search with no results, and clear the search. Check that the prototype uses your team's intended components and patterns, then ask Copilot to revise anything that does not match. + +Use sample data throughout. Keep production credentials and real customer data out of the prototype. + +**Ready to continue:** you have a useful local prototype using your team's approved guidance, kept separate from the saved starting version. It has not been published to Hub. + +## Continue when you are ready to share + +Keep this repository and the work completed above. You can share a team starting point through GitHub without Hub, or add hosted publishing and comments later. + +### Share a team starting point without Hub + +Review the app, active guidance, and any starting pages your team will reuse. Confirm the GitHub owner, repository visibility, and access before creating a repository or pushing files. + +For a new GitHub repository, authorize Copilot to create it or connect an agreed empty repository as `origin`, then push the saved starting version on the intended default branch. Approve any further local commits separately. Keep prototype-specific work on its separate branch. For an existing shared repository, use its contribution process to merge the reviewed changes. Preserve its files, remote, and history. + +**Ready to share:** the repository's actual default branch on GitHub contains the reviewed app and active guidance. Teammates with repository access can use it locally, even while hosting or Actions approval is pending. This does not publish a Hub preview or enable shared review comments. + +### Add hosted publishing and comments + +If your team's Hub already shows a successful Build for the repository's reviewed default branch, continue at [step 7: Connect your canvas to Hub](prototype-environment.md#7-connect-your-canvas-to-hub). + +If Hub exists but the repository connection or build workflow still needs setup, use [step 6: Connect GitHub and enable builds](prototype-environment.md#6-connect-github-and-enable-builds). Reuse the existing Hub and GitHub App rather than setting them up again. + +If hosting has not been set up, check the [hosting requirements](prototype-environment.md#1-check-readiness-before-you-start). Once those are in place, continue at [step 5: Deploy the hub](prototype-environment.md#5-deploy-the-hub). The repository setup, guidance, and local prototype are already complete; continue from there without repeating them. + +If you already shared the starting version on GitHub, skip that part of hosted step 6 and continue at [Connect the repository to the GitHub App](prototype-environment.md#connect-the-repository-to-the-github-app). If the App already includes the repository, continue at [Enable the build workflow](prototype-environment.md#enable-the-build-workflow). diff --git a/docs/prototype-environment.md b/docs/prototype-environment.md index 4cdde0d3..dfa68404 100644 --- a/docs/prototype-environment.md +++ b/docs/prototype-environment.md @@ -1,137 +1,257 @@ -# Set up and configure your prototype environment +# Set up shared hosting and team feedback -Give your organization a shared place to create prototypes with its own components and design guidance, publish them, and collect feedback in Replica Hub. +Set up Replica so your team can build prototypes with its design system, share them, and collect feedback. This guide walks you through each step, from checking hosting requirements to publishing your first prototype. -This guide is for the people setting up and maintaining that environment, not everyone creating a prototype. It covers the starter repository, design-system guidance, Docker deployment, GitHub connection, and handoff to your team. If your organization already has an environment, follow [Get started with Replica](getting-started.md) to join it instead. +If you only want to try Replica locally, follow [Create your first local prototype](local-prototyping.md). If your team already has a connected repository and Hub, follow [Join your team's Replica environment](getting-started.md). -For a local prototype repository without hosted publishing or comments, use [prototype repository setup](prototype-repository-setup.md). It does not require the server, domain, Docker, or GitHub App described below. +Build and test prototypes in your local development environment, then publish them to Hub for your team to review and comment on. Your organization sets up and manages the server for Hub, rather than using a service hosted by GitHub. -The linked technical guides own deployment configuration, access rules, and recovery procedures. Keep them open as you work through the steps below. +Confirm the server, dedicated domain, network access, and GitHub permissions needed for Hub. While hosting is arranged, set up your prototype repository with your team's design-system guidance and build a working prototype locally. Once Hub is running and connected to the repository, publish that prototype and collect comments from your team. -## Who should be involved +You can handle setup yourself or work with your infrastructure and GitHub administrators. The linked guides provide technical details for each step. -A designer or design-system maintainer leads the product guidance and starting pages. An engineer helps connect packages and get builds working. Your organization's infrastructure and GitHub administrators deploy the hub and connect repositories. +## 1. Check readiness before you start -You will need a GitHub organization, permission to create a prototype repository and install a private GitHub App, and a Linux server with Docker and the Docker Compose plugin. You also need a dedicated domain, DNS access, and a hosting service or reverse proxy that can provide HTTPS for Hub and its wildcard preview addresses. +Before setting up Hub, confirm what is available, what needs approval, and who will handle any remaining setup. -The person preparing the prototype repository needs the [GitHub Copilot app](https://github.com/features/ai/github-app), [Git](https://git-scm.com/), [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm), and [Node.js](https://nodejs.org/). Use a Node.js version matching `engines.node` in [starter/package.json](../starter/package.json). npm comes with the Node.js installation, so you do not need to install it separately. Reuse an existing compatible installation, or arrange an approved installation with an engineer. The starter does not install these tools. +- **A server for Hub.** Confirm that the server runs Linux, supports Docker and Docker Compose, keeps data between restarts, and has backups. It must be allowed to download Replica and connect to GitHub. See the [server requirements](../hub/docs/deployment.md#requirements) and [network requirements](../hub/docs/deployment.md#outbound-network-access). +- **A dedicated domain.** Reserve an entire domain for Hub and its previews, with no unrelated apps using it. Confirm that you can configure DNS and HTTPS for Hub and its wildcard preview addresses. See [why a subdomain on a shared domain is not enough](../hub/docs/deployment.md#choose-an-isolated-domain). +- **GitHub permissions.** Determine whether your organization can install Replica's private [GitHub App](../hub/docs/github-app-setup.md#setup) and run its [build workflow](../hub/docs/github-actions-builds.md). The App must be created under your organization. Check any restrictions on actions and downloads. +- **Approval and ongoing support.** Check whether your organization needs to approve Hub, Copilot, the Replica plugin, or the AI service your team uses. Agree who will look after Hub, its passwords and access keys, and its backups. -Keep the two environments separate: the prototype repository runs locally on authors' computers, while the Hub container runs on your organization's server. Authors joining later do not need their own Hub or Docker installation. +Use sample data for prototypes. Do not include passwords or access keys from live systems, or real customer data. -Authors using the canvas preview workflow need macOS or Linux, with `lsof` available on the machine running the extension for server discovery. Install `lsof` with the system's package manager if needed. The canvas's **Start dev server** action supports only macOS and Linux. +**Ready to continue:** you have identified the hosting requirements and any approvals needed. You can start the local work below while hosting is arranged, as long as you have approval to use Copilot and the local tools. -Install [GitHub CLI](https://cli.github.com/) on the author's computer for canvas branch and publishing checks. Run `gh auth status --hostname github.com` to check authentication. If needed, run `gh auth login --hostname github.com` and sign in with an account that can access the prototype repository. Copilot sign-in and Hub approval do not replace this step. +### If hosting is blocked -## 1. Create the team's prototype repository +You can build your prototype locally while hosting is being arranged. Follow steps 2 through 4 below, and prepare starting pages in step 9 if useful. Once the hosting requirements are in place, continue at step 5 with the same project. -Follow steps 1 through 3 of [prototype repository setup](prototype-repository-setup.md) to create an independent starter, open a fresh Copilot session, and verify its local preview. Then return here to prepare the team's guidance and starting pages. +If GitHub approvals are also pending, keep working locally. You can share your code once you have an approved repository, even if the build workflow is still awaiting approval. You'll need the workflow approved and working before you can publish to Hub. -Use a GitHub repository in your organization for this shared environment. Give prototype authors write access and reviewers read access. Keep production credentials and real customer data out of it. Continue below to prepare guidance and starting pages before inviting the team. +To share the reviewed code while hosting is pending, follow [Share the reviewed starting version](#share-the-reviewed-starting-version) in step 6. Stop before the GitHub App and build setup, which need Hub. -## 2. Add your product and design-system guidance +## 2. Connect a prototype repository -Run `/setup-skills` in the new repository. Provide the product documentation, design-system documentation, and component or token packages your team wants Copilot to follow. Use only sources your organization permits you to access. +**You can start prototyping even if Hub is not ready.** Set up your team's repository and design-system guidance in your local development environment while hosting is arranged. You'll connect to Hub later to publish prototypes and collect comments. -Copilot checks the sources, offers any needed package installations for your approval, and drafts guidance. Designers and design-system maintainers should review the drafts for accuracy and approve their activation. Drafting guidance does not activate it automatically. +You'll use the **Replica canvas**, a panel in the GitHub Copilot app that shows your running prototype beside your conversation. It is included in the Replica plugin. -Try a small change using the approved guidance. Confirm that Copilot uses the intended components and patterns, not just similar-looking replacements. Have an engineer resolve package or build problems before the repository becomes your team's starting point. +If you already have a Replica repository, open it in Copilot and continue at **Install the Replica plugin if needed** below. You don't need to copy the starter files or start again. If the app already works in the canvas, go to step 3. -The [starter guide](../starter/README.md) explains the included app and skills. The [setup and troubleshooting guide](../starter/SETUP.md) covers technical canvas integration and installation errors. +If you already built a local prototype with approved guidance, keep that work and continue at step 5 once the hosting requirements are in place. If Hub is already running, continue at step 6 instead. -## 3. Prepare useful starting pages +### Prepare your local development environment -Add a small set of representative pages with sample data, such as a list, a detail page, and an empty state. Choose pages that help teammates explore common product questions. +If you don't already have the [GitHub Copilot app](https://github.com/features/ai/github-app), install it and sign in. You also need [Git](https://git-scm.com/), [Node.js](https://nodejs.org/), and npm. Use a Node.js version matching `engines.node` in your repository's `package.json`, or [the starter's package.json](../starter/package.json) for a new repository. Reuse a compatible installation. -The hub always offers **Default**, which opens the repository's root page. To offer additional templates, declare their names, descriptions, and routes in `.github/replica.json`. See [template configuration](../hub/docs/github-actions-builds.md#uploaded-artifact) for the format and limits, and [templates in the hub](../hub/docs/gallery.md#templates) for how people use them. +The Replica canvas supports local previews on macOS and Linux. It uses `lsof` to find running local servers. Install missing tools through your organization's approved process. The starter installer does not install Node.js or change your shell configuration. -Review the pages and guidance together, then follow [share the baseline on GitHub](prototype-repository-setup.md#share-the-baseline-on-github) to create or use the intended organization repository, connect `origin`, and commit and push the reviewed baseline when authorized. For an existing shared repository, merge through its contribution process. Verify the actual default branch contains the baseline before continuing to Hub setup. New prototypes start from that shared version without changing it. +Copilot requires GitHub sign-in, but creating the local starter does not require GitHub repository access. You can use a Copilot plan or [connect your own model provider](https://docs.github.com/en/copilot/how-tos/github-copilot-app/use-byok-models). -## 4. Deploy the hub +### Create a starter if you need one -Your organization hosts Hub; GitHub does not host it for you. Use the published Hub image and Docker Compose bundle rather than the contributor devcontainer. The deployment runs one Hub container with its databases and Build files in a persistent Docker volume. +The starter provides a working app to build on. The installer creates a new folder for it, named `my-prototype` in the example below. Choose a name that is not already in use. -Reserve an entire dedicated domain for the hub and its preview subdomains. A subdomain on a domain shared with unrelated applications is not enough to isolate prototype code from those applications. +In a terminal, go to the directory where you want the new folder created, then download the installer: -### Download and initialize the container deployment - -On your Linux server, follow [Download the deployment bundle](../hub/docs/deployment.md#download-the-deployment-bundle) to select an explicit stable `hub-v*` release, download its public bundle and checksum, verify the archive, and extract it into a new deployment directory. Do not use `releases/latest` or skip checksum verification. The public release assets do not require GitHub authentication. +```sh +curl -fLSs https://raw.githubusercontent.com/github/replica/main/scripts/install-starter.sh -o install-starter.sh +``` -From the extracted deployment directory, run: +Review the installer, then run it with a name for your new project folder: ```sh -./replica init +bash install-starter.sh my-prototype ``` -Enter the public hostname you chose for Hub. Initialization downloads the configured container image, creates a private `.env` file with deployment secrets, and prints the setup code for the first GitHub App connection. Keep that code available for step 5. +This creates `my-prototype` as an independent local Git repository. It does not create a GitHub repository, commit files, or publish anything. + +In Copilot, choose **Projects → + → Local folder or repository** and add the new folder. Before accepting its setup settings, review `.github/github-app.yml` and the copied README. Setup can install Copilot's command-line tool, the Replica plugin, and project dependencies. -Keep `.env` outside Git and preserve it for the lifetime of the deployment. Do not rerun initialization on an existing deployment: new encryption keys cannot read credentials saved with the old keys. +Start a fresh session in the new repository so Copilot can find its included skills. If another session created the folder, give the new session a summary of completed setup and what you want to build. -### Configure DNS and HTTPS +### Install the Replica plugin if needed -For a Hub at `hub.example.com`, create DNS records for `hub.example.com` and `*.preview.hub.example.com` pointing to the server. Configure HTTPS for both addresses and forward both to the Hub service, which listens on `127.0.0.1:3000` by default. A custom proxy must preserve the original host and HTTPS scheme. +If the Replica plugin appears under **Customize → Installed**, continue at **Open the app in the canvas** below. -Follow [DNS and HTTPS setup](../hub/docs/deployment.md#configure-dns-and-https) and [trusted proxy configuration](../hub/docs/deployment.md#client-ip-addresses-and-trusted-proxies) for your hosting platform. Verify client IP reporting and prevent direct access around your public proxy before relying on request limits or audit addresses. +The Replica starter installs the plugin during session setup. It checks for Copilot CLI and installs it if missing. Check the session setup output for dependency or plugin failures. If setup failed, resolve the reported error, then run `node scripts/setup-replica-plugin.mjs` from the repository folder to retry plugin setup. -### Start Hub and protect its data +For repositories without that setup script, use the manual plugin commands below. These require the `copilot` command in your terminal. Check with `copilot --version`; if the command is not found, follow the [Copilot CLI installation instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli) before continuing. -From the same deployment directory, run: +These commands install Replica from its default branch. If your organization requires a specific version or source, use its installation instructions instead. + +First, add Replica's plugin marketplace if you haven't already: ```sh -./replica up -./replica status +copilot plugin marketplace add github/replica +``` + +Then install the Replica plugin: + +```sh +copilot plugin install replica-prototype@replica +``` + +### Open the app in the canvas + +With the plugin installed, enable the canvas and try the app before making changes. In Copilot, open **Customize → Installed** and enable both the Replica plugin and its canvas extension. They are separate switches. + +Start a fresh session after installation or enablement, then choose **+ → Canvas → Replica prototype**. Keep only one copy of the Replica canvas enabled. + +Ask Copilot: + +```text +Run this repository's app locally and show it in the Replica canvas. +Use the run commands in its README and the URL printed by the server. +Do not change the app, connect to Hub, or publish anything yet. ``` -The start command waits for the health check and prints the setup address. Open your Hub's HTTPS `/setup` page, then continue with step 5. If startup fails, use `./replica logs` and the [deployment guide](../hub/docs/deployment.md) to investigate before retrying. +If the canvas lists running servers, choose **Connect** beside your app's server. If none is running, choose **Start dev server**. Once the page appears, try its navigation and any included interactions. Installing dependencies or completing `/setup-skills` does not confirm that the preview works. -Arrange consistent backups of the databases and Build files, and a separate protected backup of `.env` and encryption secrets. Follow [Backups and restore](../hub/docs/backups-and-restore.md) before inviting the wider team. A running container is not a backup. +If installation fails, use the error and recovery instructions in the terminal or session setup output. Resolve policy or permission errors through your organization's approval process rather than bypassing them. If the canvas is missing, confirm both switches are enabled and start a fresh session after changing them. For preview errors, ask Copilot to investigate using the repository's README and, where present, `SETUP.md` before continuing. -## 5. Connect the repository and enable builds +**Ready to continue:** the app works in your canvas. You have not connected to Hub or published anything. -Open `/setup` on your deployed Hub, enter the setup code printed during initialization, and follow [GitHub App setup](../hub/docs/github-app-setup.md). Create the private App under your GitHub organization and install it on the prototype repository. A private App owned by a personal account allows only that person to sign in. Keep the App private and check the intended review audience before connecting a public repository. +## 3. Add your product and design-system guidance -Enroll the person administering the hub through `/operator/enrollment`, following the [operator enrollment instructions](../hub/docs/security-audit.md#enroll-an-operator). Creating the App does not grant that role automatically. +Give Copilot the information it needs to build prototypes that follow your team's product and design system. -Sign in to the hub with a GitHub account that has write access to the prototype repository. Open that repository and choose **Open installation pull request**. Review and merge the proposed `.github/workflows/replica.yml` workflow. See [repository workflow installation](../hub/docs/github-actions-builds.md#install-the-repository-workflow). +If the repository already uses your team's approved guidance, review what is in place and continue to step 4. You do not need to create it again. -Confirm that the default branch builds successfully and the hub imports the result. The **Templates** catalog below the **Create** form should show the starting pages you prepared. If a build fails, follow its error and workflow output; a working local preview does not prove the published build will work. +Otherwise, run `/setup-skills` in your prototype session. Share approved product documentation, design-system guidance, and any component packages your team uses. -## 6. Connect the Replica prototype canvas +Copilot drafts instructions from those sources and asks permission before installing packages. Review the drafts using your team's usual approval process and request any corrections. Once the drafts are reviewed, give Copilot separate approval to apply them. Ask it to confirm which guidance is now in use. -Set your team's Hub URL in `.github/replica.json` in the prototype repository so authors do not have to enter it manually: +You do not need to connect Hub to complete this step. Resolve any package installation or build errors before continuing. -```json -{ - "version": 1, - "hub": { - "origin": "https://hub.example.com" - } -} +## 4. Build a useful first prototype + +Choose a small task your team wants to explore. Ask Copilot to build it using the approved guidance and sample data. For example: + +```text +Build a searchable project list using our approved design-system guidance. +Use sample data. Include an empty result state and a way to clear the search. +Show it in the Replica canvas. +Before editing, check that the reviewed app and guidance are committed. +If this is a new repository with no commits, ask for my approval to save +that starting version in a local commit on its initial branch. +Use a separate branch for this prototype. Leave the default branch unchanged. +Ask for approval before making any commits. Do not push or publish anything. ``` -Replace the example with your deployed Hub's HTTPS origin: the scheme and hostname, with a port if needed, but no path, query, or fragment. If the file already contains templates or other settings, add `hub.origin` without replacing those settings. +The prompt asks Copilot to preserve a reusable starting version before experimenting. A new starter needs its first local commit before a separate prototype branch can keep those versions apart. Copilot must ask for your approval to make that commit; it does not upload or publish anything. For an existing team repository, use its usual review process for changes to the shared starting point. + +Try the interactions and confirm that the prototype uses your team's components. + +**Ready to continue:** you have a working prototype that follows your team's guidance. If hosting is still being arranged, you can keep working here and prepare starting pages. Continue below when the server, domain, and required hosting approvals are ready. + +## 5. Deploy the hub + +If Hub is already running, reuse it and continue at step 6. You do not need to deploy another Hub. + +Follow the [Hub deployment guide](../hub/docs/deployment.md) on the Hub server, or share it with the person handling deployment. This can happen alongside steps 2 through 4. Use the released installation package, not the developer setup. + +Deployment includes downloading and checking the installation files, creating Hub's settings, setting up DNS and HTTPS, and starting Hub. The `./replica init` command creates settings; it does not complete all these steps. + +Keep the Hub web address and the setup code printed during installation for step 6. Store the private settings file (`.env`) securely and never add it to a Git repository. Do not run `./replica init` again on an existing installation. Keep the original security keys; new keys cannot read the saved GitHub connection details. + +Check the [web forwarding settings](../hub/docs/deployment.md#client-ip-addresses-and-trusted-proxies) and arrange [backups and recovery](../hub/docs/backups-and-restore.md) before the wider team joins. + +Open the setup page at your Hub address, such as `https://hub.example.com/setup`. If it does not open, run `./replica logs` on the Hub server and follow the [startup troubleshooting instructions](../hub/docs/deployment.md#troubleshoot-startup). + +**Ready to continue:** the setup page opens, and DNS and HTTPS are configured for both Hub and its previews. Publishing is not tested yet. + +## 6. Connect GitHub and enable builds + +With Hub running, connect the repository and enable its build workflow. If Hub already shows a successful Build for the repository's reviewed default branch, continue at step 7. + +### Share the reviewed starting version + +If your project is not on GitHub yet, agree which organization will own the repository and whether it should be private or public. Give prototype authors write access and reviewers read access. + +If the reviewed app and approved guidance are already on GitHub's default branch, reuse that version and continue at **Connect the repository to the GitHub App** below. + +Otherwise, ask Copilot to connect the agreed GitHub repository and upload the saved starting version to its intended default branch. Approve any repository creation, commits, and uploads before they proceed. Keep your prototype on its own branch. For an existing shared repository, use its usual review process; do not replace its files, remote, or history. + +### Connect the repository to the GitHub App + +Check the [prototype requirements](../hub/docs/github-actions-builds.md#prototype-requirements) before connecting the repository. + +For a new Hub, open its `/setup` page and enter the setup code from step 5. Follow the [GitHub App setup instructions](../hub/docs/github-app-setup.md#setup) to create a private App owned by your organization and install it on the prototype repository. + +For an existing Hub, reuse its GitHub App and include this repository in the App's installation on GitHub. If the repository is already included, no installation change is needed. Do not repeat Hub's initial setup. + +Do not create the App under a personal account for a team environment: only that person would be able to sign in. Keep the App private. Before connecting a public repository, review [who will be able to access its reviews](../hub/docs/authentication-and-repository-authorization.md#app-ownership-and-repository-visibility). + +If Hub does not have an administrator yet, the person who will look after it must [register as a Hub administrator](../hub/docs/security-audit.md#enroll-an-operator). Creating the App does not give them that role automatically. + +### Enable the build workflow + +Sign in to Hub with a GitHub account that has write access to the repository. If the Replica build workflow is already installed, check its latest default-branch Build instead of installing it again. If it needs updating, follow the [workflow installation instructions](../hub/docs/github-actions-builds.md#install-the-repository-workflow). + +If the workflow is not installed, open the repository in Hub and choose **Open installation pull request**. This proposes a GitHub Actions workflow that prepares your app for publishing. Review and merge it using your team's usual review process and the workflow installation instructions above. + +Wait for the workflow to finish and for Hub to download the result. Hub calls each prepared version a **Build**. If the workflow fails or a download is denied, investigate the displayed error. + +**Ready to continue:** Hub shows a successful Build for the repository's default branch. A successful GitHub workflow alone is not enough. + +## 7. Connect your canvas to Hub + +Install [GitHub CLI](https://cli.github.com/) on your computer if needed. Sign in with an account that can access the repository. Copilot sign-in does not sign you in to GitHub CLI. + +[Save your team's Hub address in the repository](../starter/README.md#connect-to-hub), in `.github/replica.json`. Keep any existing settings in that file. Review and merge the change into the default branch so teammates can use it too. + +Saving the address does not grant access. Each person must still approve their own connection to Hub. + +Open your prototype session and its canvas. If the app is not running, ask Copilot to start it and show it in the canvas. + +Choose **Connect to the hub** and enter your team's Hub URL if asked. In the browser, check the Hub address, repository, and approval code. Approve only if they match what the canvas shows. + +If the canvas points to a different Hub, follow the [Hub switching instructions](../hub/docs/prototype-canvas.md#repository-hub-discovery). For approval problems, see [connection approval](../hub/docs/prototype-canvas.md#pairing-and-review). + +**Ready to continue:** you can use the app in the canvas and have approved its connection to your team's Hub. Connecting does not publish anything. + +## 8. Publish your prototype and exchange feedback + +Share the prototype you built with your team's guidance: + +1. Open your prototype session. Ask Copilot to confirm that you are on the prototype's branch, not the default branch. Check the result in the canvas. +2. Choose **Publish** and approve saving and uploading your prototype changes. Wait until the canvas says **Published**. A completed upload alone does not mean Hub is ready to show it. +3. Open **Share prototype**, copy the **Internal prototype link**, and send it to your teammate. +4. Ask them to sign in, open the prototype, and leave a comment. They need at least read access to the repository. +5. Check that you can read their comment in your connected canvas. + +If publishing or comments do not work, investigate the displayed error. You can continue prototyping locally while resolving it. + +Use the internal link for this first review. Public sharing is off by default and should stay off unless your organization decides to enable it. See [share links](../hub/docs/share-links.md). + +**Ready to continue:** your teammate can open the published prototype and leave a comment, and you can read that comment in the canvas. + +## 9. Prepare useful starting pages -Commit the configuration and merge it into the repository's actual default branch. The canvas discovers the URL from that branch, not from unmerged prototype changes. Discovery requires GitHub CLI authenticated with access to the repository. +Create a few pages your teammates can use as starting points. For example, a list, a detail page, and an empty state might help them try common product ideas. Use sample data. -This configures the Hub address, not authorization. Each author must still choose **Connect to the hub** and approve the connection in their browser. An existing saved Hub selection takes precedence over repository configuration; changing the file does not silently switch an author's Hub. See the [canvas guide](../.github/extensions/replica-prototype/README.md) for discovery and switching details. +You can prepare these pages before Hub is ready. If you already have them, review and reuse them rather than creating them again. -Install the Replica prototype plugin through Copilot CLI using the [canvas installation instructions](../.github/extensions/replica-prototype/README.md#install). Choose the repository's default branch or an approved release tag. +Hub already offers **Default**, which opens your app's main page. To offer other starting pages, add them to `.github/replica.json` using the [template instructions](../hub/docs/github-actions-builds.md#uploaded-artifact). Keep the Hub address you added earlier in that file. -Keep only one copy of the canvas enabled in a session. +Review the guidance and pages together. Have the approved changes merged into the default branch using your team's usual review process. Wait for the updated Build to appear in Hub, then check that the **Templates** list shows the starting pages you expect. -Open the canvas in a prototype session and connect its local preview. Choose **Connect to the hub**, enter your organization's hub URL if needed, and approve the connection in your browser after checking that the codes match. See [canvas connection and approval](../hub/docs/prototype-canvas.md#pairing-and-review). +**Ready to continue:** your team's shared version has approved guidance and working starting pages. New prototypes can use that version without changing it. -## 7. Try the whole flow before inviting the team +## 10. Invite the team -Ask one prototype author to follow [Get started with Replica](getting-started.md), beginning with adding your shared repository to the Copilot app. They should be able to start a session, make a change on a new branch, connect the canvas, publish, and copy an internal link. Ask a reviewer to sign in, open that link, and leave a comment. Also check that the author can read that feedback in the canvas. +Ask someone who did not help with setup to follow [Join your team's Replica environment](getting-started.md). Check that they can create a prototype using the approved guidance, publish it, and exchange feedback. -Use internal links for this first trial. Public sharing is off by default and needs a separate decision about who may see prototypes. Follow [Share links](../hub/docs/share-links.md) before enabling it. +Share the repository link, Hub URL, and joining guide with the team. Include any required tool or plugin versions. Tell them who to ask about the design guidance, starting pages, and Hub itself. -Once that flow works, give your team the repository's GitHub URL, Hub URL, required local tools and setup commands, any approved canvas release, and the [getting started guide](getting-started.md). Name the people who maintain the guidance and templates and the person who operates Hub so teammates know where to ask for help. Teammates should reuse this environment, not repeat the starter installation or deploy another Hub. +They should use your existing repository and Hub, not install another starter or set up another server. -## 8. Maintain the shared environment +## 11. Maintain the shared environment -Keep product guidance and starting pages current on the repository's default branch. Review and approve guidance changes before asking authors to use them. +Keep the guidance and starting pages up to date. Review changes before adding them to the default branch for everyone to use. -On the Hub server, use `./replica status` to check health and `./replica logs` to investigate failures. Use `./replica down` to stop the service without deleting data. Updates are deliberate: follow [deployment operations](../hub/docs/deployment.md#operate-the-deployment) before running `./replica update`, and retain the existing secrets and persistent storage. +The person running Hub should follow the [maintenance instructions](../hub/docs/deployment.md#operate-the-deployment) to check that it is working, investigate problems, and install updates. Keep the existing security keys and saved data when updating, and maintain the agreed backups. -Keep public sharing off unless your organization decides to enable it. Review access, link expiration, backups, and recovery ownership as part of operating the environment, not as tasks each prototype author must configure. +Review who has access and who will restore Hub if something goes wrong. If your organization enables public sharing, also review shared links and their expiration dates. The people looking after Hub handle these tasks; each prototype author does not need to repeat them. diff --git a/docs/prototype-repository-setup.md b/docs/prototype-repository-setup.md index 6c4045d2..d202049d 100644 --- a/docs/prototype-repository-setup.md +++ b/docs/prototype-repository-setup.md @@ -1,84 +1,123 @@ # Set up a prototype repository -Use this guide when someone points an agent at `github/replica` and asks it to set up a prototyping repository. The first milestone is an independent starter app with a verified local preview. Product guidance, reference components, a shared team baseline, and Hub publishing are separate milestones. +Copilot uses this guide to create a repository from the Replica starter or continue setup in an existing repository on your behalf. **The numbered steps below are instructions for Copilot.** They cover repository checks, your approvals, local preview, and the handoff to a fresh session. -This guide uses the existing installer and starter workflows. It does not change `/setup-skills`, which drafts the full shared context library on plain setup. +The first goal is to verify that the starter app, or the app in the existing repository, runs locally in the Replica canvas. Copilot then continues with the product guidance, starting pages, or publishing you requested. **Local prototyping does not need Hub or a GitHub repository.** -## 1. Resolve the target and requested outcome +For a walkthrough you can follow yourself, use [Create your first local prototype](local-prototyping.md) or [Set up shared hosting and team feedback](prototype-environment.md). Those guides contain the setup steps; this page is not an additional step you need to complete. -Reuse the repository name, destination, references, and decisions already supplied. Ask only for missing information needed for the next action. +## 1. Confirm the repository and goal -| Target | Next action | +Use the repository name, destination, references, and decisions already supplied. Ask only for information needed to take the next step. + +If the user requests hosted publishing, identify the [hosting requirements](prototype-environment.md#1-check-readiness-before-you-start) early. Hosting can be arranged alongside local work. + +| Starting point | Next step | | --- | --- | -| New local repository | Choose a new directory outside the Replica checkout, then follow step 2. | -| Existing local or GitHub repository | Inspect its instructions, files, Git state, and remote before proposing changes. If it already uses Replica, continue from its current setup state. | -| Existing empty directory or repository | Explain that the installer requires a new destination. Propose creating the starter in a separate directory and reviewing how to integrate it into the intended repository. Get approval before transferring files or changing repository configuration. | -| Existing repository with another app | Agree whether to adapt that app or create a separate prototype repository before installing anything. Preserve existing files and history. | +| New local repository | Choose a new folder outside the Replica checkout, then follow step 2. | +| Existing Replica repository | Inspect its instructions, files, Git state, and remote. Continue from its current setup state rather than installing the starter again. | +| Existing empty folder or repository | The installer needs a destination that does not exist. Propose creating the starter in a separate folder, then agree how to integrate it. Get approval before transferring files or changing repository configuration. | +| Existing repository with another app | Inspect its instructions, files, Git state, and remote. Agree whether to adapt the app or create a separate prototype repository before installing anything. If adapting it, preserve its files and history and use its setup instructions rather than copying the starter over it. | -A local repository needs no GitHub credentials or Hub. If the user also requests a GitHub repository, resolve its owner and visibility before creating it. Follow the host's authorization rules for repository creation, commits, and pushes; local setup alone does not authorize them. +If the user also requests a GitHub repository, confirm its owner and visibility before creating it. Follow the host's authorization rules for repository creation, commits, and pushes. Local setup alone does not authorize these actions. -When a reference app is supplied, retain it for the guidance and component work in step 4. A request to create the repository does not require a design-system questionnaire before copying the starter. +Keep supplied reference apps and design-system sources for step 4. Creating the starter does not require product or design-system intake first. ## 2. Create the independent starter -Without a local Replica checkout, download the installer: +Create the starter only when a new repository is needed, using the destination agreed in step 1. When continuing with an existing app, preserve it and continue at step 3. + +Download the installer: ```sh curl -fLSs https://raw.githubusercontent.com/github/replica/main/scripts/install-starter.sh -o install-starter.sh ``` -Read the downloaded script before running it. Use a destination that does not exist and whose parent directory exists: +Review the installer, then run it with a new project folder name. The destination must not exist, and its parent folder must exist: ```sh bash install-starter.sh my-prototype ``` -From a local Replica checkout, use the checked-out script instead: +If working from a local Replica checkout, use its script instead of downloading the installer: ```sh bash scripts/create-prototype-repo.sh ../my-prototype ``` -Both paths create an independent, uncommitted Git repository with no remote. They copy the starter without Replica's source history, require no GitHub credentials, and publish nothing. The installer does not install Node.js or app dependencies. +Both commands create an independent Git repository with no commits or remote. They copy the starter without Replica's source history and require no GitHub credentials. Nothing is uploaded or published. Neither command installs Node.js or app dependencies. + +Before the user accepts the new project's Copilot configuration, review `.github/github-app.yml` and the startup instructions in its `README.md`. Explain the automatic setup actions: startup can install Copilot CLI globally if missing and install or enable the Replica plugin. It also runs `npm ci`. + +### Continue in a fresh session + +Ask the user to add the repository folder to Copilot using **Projects → + → Local folder or repository**, then start a fresh session there. A session in the Replica checkout cannot discover the new repository's local skills. -Before asking the user to accept the copied repository's Copilot app configuration, review `.github/github-app.yml` and the startup details in the copied `README.md`. Explain that session startup can install Copilot CLI globally when missing, install or enable the Replica plugin, and will run `npm ci`. +Before ending the original session, provide a message the user can paste into the new one, headed **Prompt 1: Continue prototype repository setup**. The new session does not inherit the conversation. Include: -Add the new directory to the Copilot app using **Projects → + → Local folder or repository**, then start a fresh session there. The session in the Replica checkout cannot discover the copied local skills. +- The user's goal and requested outcome. +- The project path and supplied references. +- Decisions and approvals already given. +- Completed work, blockers, and the next step. -Before ending the originating session, provide a paste-ready kickoff message headed **Prompt 1: Continue prototype repository setup**. Tell the user to paste it into the fresh session; a new session does not inherit the previous conversation. Include the user's goal, repository path, supplied references, requested milestone, settled decisions and approvals, completed actions, blockers, and next step. +Tell the new session to follow the project's `AGENTS.md` and continue at [step 3 of this guide](https://github.com/github/replica/blob/main/docs/prototype-repository-setup.md#3-verify-the-existing-app-locally). Use the absolute URL because this guide is not copied into the starter. If the current instructions are not yet available at that URL, include steps 3 through 5 in the message. -The kickoff must tell the new session to follow the copied repository's `AGENTS.md` and resume this guide at step 3. Include the [absolute guide URL](https://github.com/github/replica/blob/main/docs/prototype-repository-setup.md#3-verify-the-existing-app-locally), since this guide is not copied into the starter. If that version is not yet available at the URL, include steps 3 through 5 inline instead. The new session reuses settled answers and checks which actions and approvals remain applicable. +The new session should reuse settled answers and check which approvals still apply. ## 3. Verify the existing app locally -Check `node --version` against `engines.node` in the copied `package.json`. Reuse a compatible installed runtime. On macOS or Linux, obtain approval before installing Node.js, nodenv, or node-build, or changing shell configuration. +Check `node --version` against `engines.node` in the project's `package.json`. Reuse a compatible installation. On macOS or Linux, get approval before installing Node.js, nodenv, or node-build, or changing shell configuration. -The fresh session does not receive the setup output, so ask the user to inspect it and report any failures before repeating setup. Dependency installation success does not prove that the current session loaded the canvas. +The fresh session does not receive the previous setup output. Ask the user to report startup failures before repeating setup. Successful dependency installation does not confirm that the canvas is available in the current session. -Follow the copied README's **Connect the Replica canvas** and **Canvas preflight** sections for plugin activation and recovery. Complete that preflight before starting a preview. Use its **Run it** commands, reuse an existing responsive server when appropriate, and open the actual printed URL. Verify that the included app renders; a successful dependency install or HTTP response alone is not a rendered check. +Follow the project's README sections **Connect the Replica canvas** and **Canvas preflight** to activate the plugin and check that the canvas is ready. Complete those checks before starting the preview. Use the README's **Run it** commands, reuse a responsive server when appropriate, and open the URL printed by the server. -This milestone checks the existing starter page without building product UI. Report a missing runtime, unavailable canvas, or failed preview with its specific recovery step. Hub connection is not required for local preview. +For an adapted app without those sections, use the [starter's canvas setup instructions](../starter/README.md#connect-the-replica-canvas) alongside the app's own run commands. Preserve its existing instructions. + +Verify that the existing app renders without building new product UI. A successful dependency install or HTTP response is not enough. If Node.js, the canvas, or the preview is unavailable, report the specific problem and recovery step. Hub is not required. ## 4. Continue only to the requested milestone -| Requested outcome | Continue with | -| --- | --- | -| Local starter and preview | Report the verified state and stop. No guidance authoring or Hub setup is needed just to inspect the included app. | -| Product or design-system setup | Run the new repository's `/setup-skills` with the supplied sources. Reuse prior answers. Follow its source intake, installation approval, draft review, and separate activation steps. | -| Reference-based starting UI | Complete the applicable guidance setup, then use the local `create-prototype` skill to build the requested shell or page. Establish whether components come from an installable package, permitted source reuse, or newly authored components. Verify the rendered result against the authorized reference. | -| Shared team baseline | Complete the applicable guidance setup, [prepare useful starting pages](prototype-environment.md#3-prepare-useful-starting-pages), and review them together. Then [share the baseline on GitHub](#share-the-baseline-on-github). | -| Hosted publishing and comments | First [share the reviewed baseline on GitHub and verify it on the actual default branch](#share-the-baseline-on-github), then follow [deploy the hub](prototype-environment.md#4-deploy-the-hub) and the remaining environment setup steps, or connect to an existing team Hub. | +For a local starter trial, report what works and stop after step 3. Product guidance and Hub setup are not required to try the included app. + +For the outcomes below, complete only the work needed for the user's request. + +### Add product and design-system guidance + +Run the project's `/setup-skills` with the supplied sources and reuse prior answers. Follow its source intake, package installation approvals, draft review, and separate activation steps. Plain setup drafts all documents in the shared context library unless the user requests a narrower scope. -Guidance drafts are not active guidance. Installed tokens or packages are not proof that reference components are usable or that a shell resembles the reference. Keep those outcomes distinct. +Report whether guidance is drafted, reviewed, or active. Drafting does not activate it. + +### Build from a reference + +Complete the relevant guidance setup, then use the project's `create-prototype` skill to build the requested page or app layout. Confirm whether components will come from an installable package, permitted source reuse, or new code. + +Verify the rendered result against the authorized reference. Installing tokens or packages does not confirm that the intended components work or that the page matches the reference. + +### Prepare a shared team starting point + +Complete the relevant guidance setup and build the requested starting pages. A list, detail page, and empty state are possible starting points. Review the pages and guidance together before sharing them. + +Continue with **Share the baseline on GitHub** below. This makes the reviewed app, guidance, and pages available to teammates without requiring Hub. Hub templates can be configured later as part of hosted setup. ### Share the baseline on GitHub -After reviewing the starter files, guidance, and starting pages, use the intended empty GitHub repository or create one with the agreed owner and visibility. Connect it as a remote named `origin`, make the initial commit, and push the intended default branch only when authorized. For an existing shared repository, follow its contribution process to merge the reviewed changes instead of replacing its remote or history. Ask an engineer for help with these Git steps if needed. +Use the intended empty GitHub repository or create one with the agreed owner and visibility. With authorization, connect it as `origin`, make the initial commit, and push the intended default branch. For an existing shared repository, follow its contribution process to merge the reviewed changes. Preserve its remote and history. -Verify the repository's actual default branch contains the intended baseline before calling it ready for teammates or continuing to Hub repository connection. A local preview is not evidence of a published Hub Build. +Verify that the repository's actual default branch contains the reviewed app, active guidance, and starting pages before reporting that it is ready for teammates. This is a shared source repository, not a published Hub Build. + +### Add hosted publishing and comments + +Reuse this repository and its approved guidance to build a useful prototype. Publishing is not a prerequisite for guidance setup or local prototyping. + +Once the hosting requirements are in place, continue with [step 5: Deploy the hub](prototype-environment.md#5-deploy-the-hub). The remaining hosted steps cover the GitHub connection, build workflow, canvas connection, publishing, and feedback. There is no need to repeat the repository setup above. + +If the team already has Hub, continue with the existing environment's [GitHub and build setup](prototype-environment.md#6-connect-github-and-enable-builds) instead of deploying another Hub. Skip work already completed. ## 5. Report what is ready -Finish with a short status summary based on observed results. Distinguish **verified**, **blocked**, **not checked**, and **not requested** rather than saying only "setup complete." +Finish with a short summary of observed results. Use **verified**, **blocked**, **not checked**, and **not requested** to distinguish what works from what remains. + +Cover only the relevant outcomes: Node.js and dependencies, canvas availability in the current session, rendered preview and URL, guidance activation, reference components or pages, the shared default branch, and Hub publishing. -Cover the runtime and dependencies, current-session canvas availability, rendered preview and URL, guidance activation, reference components or shell, default-branch baseline, and Hub publishing only as applicable. Name the next blocker and its recovery action. Preserve this summary across a required session handoff. +Name any blocker and its recovery action. Include this summary in a required session handoff so the next session can continue without repeating completed work. diff --git a/hub/docs/deployment.md b/hub/docs/deployment.md index f6851d96..efd72724 100644 --- a/hub/docs/deployment.md +++ b/hub/docs/deployment.md @@ -7,12 +7,27 @@ Replica Hub publishes a public container image at `ghcr.io/github/replica-hub`. The recommended deployment needs: - A server with Docker and the Docker Compose plugin. +- Outbound HTTPS access for deployment downloads and Hub's GitHub connection, as described below. - A domain you control, dedicated to Hub and its previews. - Permission to create DNS records and enable HTTPS. - A hosting service or reverse proxy that sends the Hub and preview addresses to the same server. The default deployment runs one Replica Hub container and stores its SQLite databases and Build files in one persistent Docker volume. +### Outbound network access + +Before installation, confirm these connections with your network administrator: + +| From | Destination | Purpose | +| --- | --- | --- | +| Deployment server | GitHub release downloads at `github.com` | Download the deployment bundle and checksum. | +| Deployment server | GitHub Container Registry at `ghcr.io` | Pull the Hub image during initialization, startup, and updates. | +| Running Hub container | GitHub's API at `api.github.com` and GitHub's artifact download locations | Connect the GitHub App, discover repositories and workflows, and download successful build artifacts. | + +Downloads can redirect to additional storage hosts, so these names are not a complete firewall allowlist. Ask your network administrator to approve the required download destinations as well. Check access from both the server and the running container; access from your own computer does not prove either can connect. + +If a download is denied, resolve the network approval before retrying. These requirements do not authorize bypassing your organization's network controls. + ## Choose an isolated domain Hub displays prototypes inside its review pages. It requires each preview to use a separate HTTPS subdomain, such as `b123.preview.hub.example.com` under `hub.example.com`. This lets preview cookies work while the prototype is embedded. Hub keeps its own sign-in cookie separate. From 8375d99a35444ce85e1a1697df9fb7c810356d09 Mon Sep 17 00:00:00 2001 From: Catharine McNally Date: Thu, 22 Oct 2026 21:54:04 -0400 Subject: [PATCH 2/6] Enhance prototype sharing instructions Added instructions for checking workflow presence and handling merges. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/prototype-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/prototype-environment.md b/docs/prototype-environment.md index dfa68404..bfcf8295 100644 --- a/docs/prototype-environment.md +++ b/docs/prototype-environment.md @@ -216,7 +216,7 @@ If the canvas points to a different Hub, follow the [Hub switching instructions] Share the prototype you built with your team's guidance: -1. Open your prototype session. Ask Copilot to confirm that you are on the prototype's branch, not the default branch. Check the result in the canvas. +1. Open your prototype session. Ask Copilot to confirm that you are on the prototype's branch, not the default branch, and that it includes `.github/workflows/replica.yml` from step 6. If the workflow is missing, ask Copilot to preserve your local prototype work and, with your approval, fetch and merge the reviewed default-branch changes into this branch. Resolve any conflicts before continuing. Check the result in the canvas. 2. Choose **Publish** and approve saving and uploading your prototype changes. Wait until the canvas says **Published**. A completed upload alone does not mean Hub is ready to show it. 3. Open **Share prototype**, copy the **Internal prototype link**, and send it to your teammate. 4. Ask them to sign in, open the prototype, and leave a comment. They need at least read access to the repository. From 94d6a2c357ecee9c61e9a0ea20321005992d5ff2 Mon Sep 17 00:00:00 2001 From: Catharine McNally Date: Thu, 22 Oct 2026 21:56:30 -0400 Subject: [PATCH 3/6] Enhance documentation for running Hub container Updated the running Hub container section to include GitHub sign-in requirements and clarified the connection process for the GitHub App. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- hub/docs/deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hub/docs/deployment.md b/hub/docs/deployment.md index efd72724..37c5fca5 100644 --- a/hub/docs/deployment.md +++ b/hub/docs/deployment.md @@ -22,7 +22,7 @@ Before installation, confirm these connections with your network administrator: | --- | --- | --- | | Deployment server | GitHub release downloads at `github.com` | Download the deployment bundle and checksum. | | Deployment server | GitHub Container Registry at `ghcr.io` | Pull the Hub image during initialization, startup, and updates. | -| Running Hub container | GitHub's API at `api.github.com` and GitHub's artifact download locations | Connect the GitHub App, discover repositories and workflows, and download successful build artifacts. | +| Running Hub container | GitHub sign-in at `github.com`, GitHub's API at `api.github.com`, and GitHub's artifact download locations | Complete GitHub sign-in, connect the GitHub App, discover repositories and workflows, and download successful build artifacts. | Downloads can redirect to additional storage hosts, so these names are not a complete firewall allowlist. Ask your network administrator to approve the required download destinations as well. Check access from both the server and the running container; access from your own computer does not prove either can connect. From a2ca61b381085f8661ef14ccff3132efdec59100 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Inayaili=20Le=C3=B3n?= Date: Fri, 23 Oct 2026 11:40:52 +0100 Subject: [PATCH 4/6] Improve formatting of getting started guide Reformatted instructions for clarity and readability. --- docs/getting-started.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index ed928e87..7b1ce482 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,7 +2,10 @@ Create an interactive prototype with GitHub Copilot, publish it to Replica Hub, and collect feedback from your team. This guide helps you join your organization's prototyping environment and create your first shared prototype. -Starting on your own? Follow [Create your first local prototype](local-prototyping.md), which needs no Hub. Setting up hosting for your organization? Follow [Set up shared hosting and team feedback](prototype-environment.md). Publishing and team comments need an organization-hosted Hub, a connected GitHub repository, and the repository's Replica build workflow. +* Starting on your own? Follow [Create your first local prototype](local-prototyping.md), which needs no Hub. +* Setting up hosting for your organization? Follow [Set up shared hosting and team feedback](prototype-environment.md). + +Publishing and team comments need an organization-hosted Hub, a connected GitHub repository, and the repository's Replica build workflow. ## 1. Download the GitHub Copilot app From e925f8c9e0444f24599c6971f77f9429c9147513 Mon Sep 17 00:00:00 2001 From: Catharine McNally <2089974+cmcnally@users.noreply.github.com> Date: Tue, 27 Oct 2026 06:47:24 -0700 Subject: [PATCH 5/6] docs: distinguish onboarding steps from commentary Use ordered steps for actions, lists for requirements, and tables for setup alternatives. Separate explanations and recovery help while preserving reviewer edits, existing headings, commands, and prompts. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 045ed8e1-41ea-44f3-a2c6-d9f485f87ca1 --- docs/getting-started.md | 155 +++++++++++++++------ docs/local-prototyping.md | 140 +++++++++++++------ docs/prototype-environment.md | 248 +++++++++++++++++++++++----------- 3 files changed, 379 insertions(+), 164 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 7b1ce482..cb54df10 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -9,25 +9,37 @@ Publishing and team comments need an organization-hosted Hub, a connected GitHub ## 1. Download the GitHub Copilot app -Download the [GitHub Copilot app](https://github.com/features/ai/github-app), install it, and follow its sign-in instructions. +Local canvas previews require macOS or Linux. -You also need [Git](https://git-scm.com/), [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm), and [Node.js](https://nodejs.org/). Install the Node.js version required by your team's prototyping repository; npm comes with the Node.js installation, so you do not need to install it separately. +1. Download the [GitHub Copilot app](https://github.com/features/ai/github-app), install it, and follow its sign-in instructions. +2. Check that the following tools are installed: -The canvas preview workflow below supports macOS and Linux. Server discovery requires `lsof` on the machine running the canvas extension; install it with your system's package manager if it is missing. **Start dev server** is supported only on macOS and Linux. + | Tool | Requirement | + | --- | --- | + | [Git](https://git-scm.com/) | Required for the prototype repository. | + | [Node.js](https://nodejs.org/) and [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) | Use the Node.js version required by your team's repository. npm comes with Node.js. | + | `lsof` | Required on the machine running the canvas extension to find local servers. Install it with your system's package manager if missing. | + | [GitHub CLI](https://cli.github.com/) | Required for the canvas's branch and publishing checks. | -Install [GitHub CLI](https://cli.github.com/) for the canvas's branch and publishing checks. In a terminal, check your GitHub sign-in: +3. In a terminal, check your GitHub CLI sign-in: -```sh -gh auth status --hostname github.com -``` + ```sh + gh auth status --hostname github.com + ``` + +4. If you are not signed in, run `gh auth login --hostname github.com` and follow the prompts. Use an account with access to the prototype repository. -If you are not signed in, run `gh auth login --hostname github.com` and follow the prompts. Use an account with access to the prototype repository. Copilot sign-in and Hub browser approval do not replace this GitHub CLI sign-in. +> **Note:** Copilot sign-in and Hub browser approval do not replace GitHub CLI sign-in. The canvas's **Start dev server** action is supported only on macOS and Linux. ## 2. Set up your prototyping repository Your organization should have a shared prototyping environment: a GitHub repository with your product's components and design guidance, connected to your team's Replica Hub. A designer, design-system maintainer, or engineer may already have set this up. -Ask your team for the prototype repository's GitHub URL, the Hub URL, and access. You need repository write access to publish prototypes. +Before adding the repository, get these details from your team: + +- The prototype repository's GitHub URL. +- The Hub URL. +- Repository write access, which you need to publish prototypes. Add the repository to the Copilot app: @@ -44,28 +56,50 @@ If the repository is missing or access is denied, ask its maintainer to check yo The Replica prototype canvas shows your local preview beside the Copilot conversation and adds publishing, sharing, commenting, and prototype controls. -Ask your agent to install the plugin and provide the following commands to the agent: +### Install the plugin if needed -```sh -copilot plugin marketplace add github/replica -copilot plugin install replica-prototype@replica -``` +If the plugin appears under **Customize → Installed**, continue at **Enable the plugin and canvas** below. + +Repositories using the current Replica starter setup script install the plugin automatically. That setup: + +- Installs Copilot CLI globally with `npm install -g @github/copilot` if `copilot` is missing. +- Installs the Replica plugin. +- Runs `npm ci` even if CLI or plugin setup fails. + +> **Note:** Automatic setup needs npm and a writable global installation directory. It does not use sudo or change your shell configuration. Successful dependency installation does not mean the canvas is ready. + +**If automatic setup failed:** Check the app's setup output and resolve the reported error. Follow the [Copilot CLI installation instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli) if CLI is unavailable, then rerun `node scripts/setup-replica-plugin.mjs` in repositories that have it. + +For repositories without the setup script, ask Copilot to install the plugin or run these steps in a terminal with Copilot CLI available: + +1. If Copilot CLI is unavailable, follow the [installation instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli). +2. Add the marketplace if you haven't already: + + ```sh + copilot plugin marketplace add github/replica + ``` -You can also run this manually in a terminal with Copilot CLI available. +3. Install the plugin: -Repositories using the current Replica starter setup script automatically run `npm install -g @github/copilot` if `copilot` is missing, then install the Replica plugin. This needs npm and a writable global installation directory. Setup does not use sudo or change your shell configuration. Dependency installation with `npm ci` still runs if CLI or plugin setup fails; this does not mean the canvas is ready. Check the app's setup output for the failure reason and recovery steps. If automatic installation fails, or your repository does not use that script, follow the [Copilot CLI installation instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli), then rerun `node scripts/setup-replica-plugin.mjs` in repositories that have it. + ```sh + copilot plugin install replica-prototype@replica + ``` -In the Copilot app sidebar, open **Customize**, then **Installed**. Find the `replica-prototype` plugin and enable it. Also find its `replica-prototype` canvas and enable that extension; both the plugin and extension must be enabled. +### Enable the plugin and canvas -Start a fresh session in the Copilot app, then select **+ → Canvas → Replica prototype**. +1. In the Copilot app sidebar, open **Customize → Installed**. +2. Enable the `replica-prototype` plugin. +3. Enable its `replica-prototype` canvas extension. Both switches must be enabled. +4. Start a fresh session in the Copilot app. +5. Select **+ → Canvas → Replica prototype**. If the canvas is missing, check that installation completed and that you started a new session after installing it. ## 4. Create a prototype -Start a new prototype by clicking **+** next to your prototype repository. Give each prototype its own session. Before editing, ask Copilot to confirm that the session uses a new prototype branch, not the repository's default branch. - -Describe the change you want and let Copilot build it. +1. Start a new prototype by clicking **+** next to your prototype repository. Give each prototype its own session. +2. Before editing, ask Copilot to confirm that the session uses a new prototype branch, not the repository's default branch. +3. Describe the change you want and let Copilot build it. You can use the example below. ### Example prompt: Create a searchable project list @@ -75,47 +109,64 @@ guidance and sample data. Add search, an empty result message, and a way to clear the search. Keep this separate from our live product. ``` -The replica canvas should open automatically and show your prototype. If it lists running servers, choose **Connect** beside your prototype's server. -If none is running, choose **Start dev server**. If startup fails, ask Copilot to explain the error before changing anything. +The Replica canvas should open automatically and show your prototype. + +- **Server listed:** Choose **Connect** beside your prototype's server. +- **No running server:** Choose **Start dev server**. +- **Startup fails:** Ask Copilot to explain the error before changing anything. ## 5. Connect to the Hub Now it is time to connect to the hub to publish and share your prototype. -In the Replica canvas, open **Edit details** and select **Connect to the Hub**. Enter your team's Hub URL if prompted, then continue to browser approval. - -Sign in with the GitHub account that has access to the prototype repository. Check the Hub address, repository, and approval code. -Approve only when the browser shows the same code as the canvas. +1. In the Replica canvas, open **Edit details** and select **Connect to the Hub**. +2. Enter your team's Hub URL if prompted, then continue to browser approval. +3. Sign in with the GitHub account that has access to the prototype repository. +4. Check the Hub address, repository, and approval code. Approve only when the browser shows the same code as the canvas. +5. Return to the canvas after approval. -Return to the canvas after approval. Connecting does not push or publish anything, and you can keep working locally by default. +> **Note:** Connecting does not push or publish anything. You can keep working locally by default. -If the connection fails, check the Hub URL and repository access with your team. An expired or revoked connection needs browser approval again. See [canvas connection guidance](../hub/docs/prototype-canvas.md#pairing-and-review) for more detail. +**If the connection fails:** Check the Hub URL and repository access with your team. An expired or revoked connection needs browser approval again. See [canvas connection guidance](../hub/docs/prototype-canvas.md#pairing-and-review). Administrators can follow [Hub and repository setup](prototype-environment.md#5-deploy-the-hub). ## 6. Publish your prototype -Publishing sends your prototype branch to GitHub, it gets build and added to the **Prototype** page in your organisations' Hub. Local changes are not visible to reviewers until you publish them. +Publishing sends your prototype branch to GitHub, where the workflow builds it. Hub imports the result and adds it to the **Prototype** page in your organization's Hub. Local changes are not visible to reviewers until you publish them. -To publihs your prototype, choose **Publish** in the canvas. Copilot will publish your work. +1. Choose **Publish** in the canvas. Copilot will publish your work. +2. Wait until the canvas shows **Published**. +3. Use **Edit details** to give the prototype a useful name and short description. -Wait until the canvas shows **Published**. A completed push or successful GitHub workflow is not enough: the Hub must also import the successful Build for your current version. +> **Note:** A completed push or successful GitHub workflow is not enough. Hub must also import the successful Build for your current version. -Use **Edit details** to give the prototype a useful name and short description. After making more changes, choose **Publish changes** to share the new version. +After making more changes, choose **Publish changes** to share the new version. -If publication fails, read the displayed error and open **View workflow run** when available. Ask Copilot to investigate that failure before retrying. If the build workflow is missing, ask your repository maintainer to follow [workflow installation](../hub/docs/github-actions-builds.md#install-the-repository-workflow). +**If publication fails:** + +- Read the displayed error and open **View workflow run** when available. +- Ask Copilot to investigate that failure before retrying. +- If the build workflow is missing, ask your repository maintainer to follow [workflow installation](../hub/docs/github-actions-builds.md#install-the-repository-workflow). ## 7. Share and comment -Choose **Share prototype**, the link icon beside the publishing button. The **Internal prototype link** is useful to share your prototype with your teammates. +### Share with teammates + +1. Choose **Share prototype**, the link icon beside the publishing button. +2. Copy the **Internal prototype link** and send it to your teammates. Internal links require GitHub sign-in and repository read access. They let teammates try the published prototype and add comments. -To leave feedback, open the prototype in Hub, choose **Add a comment**, and select an element or highlight a region. Use the comment-count button to find conversations, reply, and resolve or reopen them. Conversations remain available across published versions. +### Leave feedback + +1. Open the prototype in Hub. +2. Choose **Add a comment**, then select an element or highlight a region. +3. Use the comment-count button to find conversations, reply, and resolve or reopen them. -You can also read and reply to coments in the connected canvas. Starting an anchored comment there requires the local checkout's commit to match the published Build. +> **Note:** Conversations remain available across published versions. You can also read and reply to comments in the connected canvas. Starting an anchored comment there requires the local checkout's commit to match the published Build. -You can even ask your agent to review the comments people left on your prototype. +You can ask Copilot to review the comments before making changes: ### Prompt 2: Review feedback before changing the prototype @@ -124,9 +175,22 @@ Read the unresolved comments for this prototype. Summarize the feedback and sugg Do not reply to or resolve comments yet. ``` -For people without repository access, **Public share links** may be available. Public sharing is off by default and requires a Hub administrator to enable it and permission to manage links. Anyone with an active public link can view its selected Build without signing in, the link does not include team review conversations or let anonymous visitors comment. +### Share outside the repository -Check the prototype's content before creating a public link from the **Share prototype** page. Enter a label, choose an expiration, and select **Create share link**. Copy the resulting URL and delete the link when it is no longer needed. Each public link stays on its selected Build: publishing a newer version does not update that link. See [share-link guidance](../hub/docs/share-links.md) for permissions and limits. +For people without repository access, **Public share links** may be available: + +- Public sharing is off by default. A Hub administrator must enable it, and you need permission to manage links. +- Anyone with an active public link can view its selected Build without signing in. +- The link does not include team review conversations or let anonymous visitors comment. + +To create a public link: + +1. Check the prototype's content before sharing it. +2. Open **Share prototype**, enter a label, and choose an expiration. +3. Select **Create share link** and copy the resulting URL. +4. Delete the link when it is no longer needed. + +> **Note:** Each public link stays on its selected Build. Publishing a newer version does not update that link. See [share-link guidance](../hub/docs/share-links.md) for permissions and limits. ## 8. Add controls @@ -143,8 +207,13 @@ Wire them to the rendered sample data. Keep these controls in Replica's panel rather than adding settings to the product UI. ``` -After Copilot adds the definitions, reload the preview page and open **Controls**, the sliders icon in the canvas toolbar. Change each setting and check that the prototype responds. **Reset all controls** restores the defaults. +After Copilot adds the definitions: + +1. Reload the preview page and open **Controls**, the sliders icon in the canvas toolbar. +2. Change each setting and check that the prototype responds. Use **Reset all controls** to restore the defaults. +3. Publish the changes to make them available in Hub previews too. +4. To share a particular scenario, select **Include current control settings** on the canvas sharing page before copying the internal or public link. -Controls work locally without the Hub. Publish the changes to make them available in Hub previews too. To share a particular scenario, select **Include current control settings** on the canvas sharing page before copying the internal or public link. Publish any new control definitions first, a link cannot add controls missing from its Build. +> **Note:** Controls work locally without Hub. Publish any new control definitions before sharing a scenario; a link cannot add controls missing from its Build. -The [starter Controls guide](../starter/README.md#prototype-controls) covers authoring and recovery. If a control is disabled or reports an error, ask Copilot to investigate the displayed reason rather than assuming the change took effect. +**If a control is disabled or reports an error:** Ask Copilot to investigate the displayed reason rather than assuming the change took effect. The [starter Controls guide](../starter/README.md#prototype-controls) covers authoring and recovery. diff --git a/docs/local-prototyping.md b/docs/local-prototyping.md index 770aa352..be4f5b04 100644 --- a/docs/local-prototyping.md +++ b/docs/local-prototyping.md @@ -8,13 +8,22 @@ You'll use the **Replica canvas**, a panel in the GitHub Copilot app that shows For a quick trial, stop after the app works in the canvas in step 4. Continue through steps 5 and 6 to build with your team's guidance. -If your team already has a connected repository and Hub, follow [Join your team's Replica environment](getting-started.md). For the full team setup, including hosting, use [Set up shared hosting and team feedback](prototype-environment.md). +- **Joining an existing setup?** Follow [Join your team's Replica environment](getting-started.md) if your team has a connected repository and Hub. +- **Setting up hosting?** Follow [Set up shared hosting and team feedback](prototype-environment.md). ## 1. Prepare your local development environment -If you don't already have the [GitHub Copilot app](https://github.com/features/ai/github-app), install it and sign in. You also need [Git](https://git-scm.com/), [Node.js](https://nodejs.org/), and npm. Use a Node.js version matching `engines.node` in your repository's `package.json`, or [the starter's package.json](../starter/package.json) for a new repository. Reuse a compatible installation. +Check that your local development environment has: -The Replica canvas supports local previews on macOS and Linux. It uses `lsof` to find running local servers. Install missing tools through your organization's approved process. The starter installer does not install Node.js or change your shell configuration. +- **The [GitHub Copilot app](https://github.com/features/ai/github-app)**, installed and signed in. +- **[Git](https://git-scm.com/)**. +- **[Node.js](https://nodejs.org/) and npm**, with a Node.js version matching `engines.node` in your repository's `package.json`, or [the starter's package.json](../starter/package.json) for a new repository. +- **macOS or Linux**, the supported systems for local canvas previews. +- **`lsof`**, which the canvas uses to find running local servers. + +Reuse compatible installations and install missing tools through your organization's approved process. + +> **Note:** The starter installer does not install Node.js or change your shell configuration. Copilot requires GitHub sign-in, but creating the local starter does not require GitHub repository access. You can use a Copilot plan or [connect your own model provider](https://docs.github.com/en/copilot/how-tos/github-copilot-app/use-byok-models). @@ -28,31 +37,39 @@ If you already have a Replica repository, use **Open an existing repository** be The installer creates a new folder for your prototype, named `my-prototype` in the example below. Choose a name that is not already in use. -In a terminal, go to the directory where you want the new folder created, then download the installer: +The new folder is an independent local Git repository. The installer does not create a GitHub repository, commit files, or publish anything. -```sh -curl -fLSs https://raw.githubusercontent.com/github/replica/main/scripts/install-starter.sh -o install-starter.sh -``` +> **Before accepting Copilot setup:** Session startup can install Copilot CLI globally if missing, install or enable the Replica plugin, and install app dependencies with `npm ci`. -Review the installer, then run it with a name for your new project folder: +1. In a terminal, go to the directory where you want the new folder created, then download the installer: -```sh -bash install-starter.sh my-prototype -``` + ```sh + curl -fLSs https://raw.githubusercontent.com/github/replica/main/scripts/install-starter.sh -o install-starter.sh + ``` -This creates `my-prototype` as an independent local Git repository. It does not create a GitHub repository, commit files, or publish anything. +2. Review the installer, then run it with a name for your new project folder: -In the Copilot app, choose **Projects → + → Local folder or repository** and add the new folder. Before accepting its repository configuration, review `.github/github-app.yml` and the copied README. Session startup can install Copilot CLI globally if missing, install or enable the Replica plugin, and install app dependencies with `npm ci`. + ```sh + bash install-starter.sh my-prototype + ``` -Start a fresh session in the new repository so Copilot can discover its included skills. If another session created the folder, give the new session a summary of completed setup and what you want to build. +3. In the Copilot app, choose **Projects → + → Local folder or repository** and add the new folder. +4. Before accepting its repository configuration, review `.github/github-app.yml` and the copied README. +5. Start a fresh session in the new repository so Copilot can discover its included skills. If another session created the folder, give the new session a summary of completed setup and what you want to build. Continue at step 3. ### Open an existing repository -Choose the repository from **Projects** in Copilot. If it is not listed, choose **Projects → + → Local folder or repository** for a local copy, or **Projects → + → Add GitHub repository** to select your team's repository on GitHub. Start a session in that repository and review any setup configuration before accepting it. +1. Choose the repository from **Projects** in Copilot. If it is not listed, add it using one of these options: -If the repository does not already use Replica, ask Copilot to inspect its instructions, app, and Git state before changing it. Agree whether to adapt the existing app or create a separate starter repository. Preserve the existing files, remote, and history. + | Repository location | Choose | + | --- | --- | + | A local copy | **Projects → + → Local folder or repository** | + | Your team's repository on GitHub | **Projects → + → Add GitHub repository** | + +2. Start a session in that repository and review any setup configuration before accepting it. +3. If the repository does not already use Replica, ask Copilot to inspect its instructions, app, and Git state before changing it. Agree whether to adapt the existing app or create a separate starter repository. Preserve the existing files, remote, and history. **Ready to continue:** the repository is open in Copilot. Opening it does not push changes or publish a prototype. @@ -68,31 +85,40 @@ Check the session setup output for dependency or plugin failures. Successful dep If the Replica plugin appears under **Customize → Installed**, continue at [Activate the plugin and canvas](#activate-the-plugin-and-canvas) below. -The Replica starter installs the plugin during session setup. It checks for Copilot CLI and installs it if missing. If setup failed, resolve the reported error, then run `node scripts/setup-replica-plugin.mjs` from the repository folder to retry plugin setup. +The Replica starter installs the plugin during session setup. It checks for Copilot CLI and installs it if missing. -For repositories without that setup script, use the manual plugin commands below. These require the `copilot` command in your terminal. Check with `copilot --version`; if the command is not found, follow the [Copilot CLI installation instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli) before continuing. +- **If starter setup failed:** Resolve the reported error, then run `node scripts/setup-replica-plugin.mjs` from the repository folder to retry plugin setup. +- **If your repository has no setup script:** Use the manual installation steps below. -These commands install Replica from its default branch. If your organization requires a specific version or source, use its installation instructions instead. +> **Before installing manually:** These commands install Replica from its default branch. If your organization requires a specific version or source, use its installation instructions instead. -First, add Replica's plugin marketplace if you haven't already: +For manual installation: -```sh -copilot plugin marketplace add github/replica -``` +1. Check that `copilot` is available in your terminal with `copilot --version`. If it is not found, follow the [Copilot CLI installation instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli). +2. Add Replica's plugin marketplace if you haven't already: -Then install the Replica plugin: + ```sh + copilot plugin marketplace add github/replica + ``` -```sh -copilot plugin install replica-prototype@replica -``` +3. Install the Replica plugin: + + ```sh + copilot plugin install replica-prototype@replica + ``` ### Activate the plugin and canvas -In the sidebar, open **Customize → Installed** and enable both the `replica-prototype` plugin and its canvas extension. They are separate switches. +1. In the sidebar, open **Customize → Installed**. +2. Enable both the `replica-prototype` plugin and its canvas extension. They are separate switches. +3. Start a fresh session after installation or enablement. +4. Open **+ → Canvas → Replica prototype**. Keep only one copy of the Replica canvas enabled. -Start a fresh session after installation or enablement. Open **+ → Canvas → Replica prototype**. Keep only one copy of the Replica canvas enabled. +**If setup fails:** -If installation fails, use the error and recovery instructions in the terminal or session setup output. Resolve policy or permission errors through your organization's approval process rather than bypassing them. If the canvas is still missing, confirm both switches are enabled and start a fresh session after changing them. +- **Installation failure:** Use the error and recovery instructions in the terminal or session setup output. +- **Policy or permission error:** Resolve it through your organization's approval process rather than bypassing it. +- **Missing canvas:** Confirm both switches are enabled and start a fresh session after changing them. **Ready to continue:** the Replica canvas opens in your current session. You do not need to connect it to Hub. @@ -108,9 +134,12 @@ Use the run commands in its README and the URL printed by the server. Do not change the app, connect to Hub, or publish anything yet. ``` -If the canvas lists running servers, choose **Connect** beside your app's server. If none is running, choose **Start dev server**. +Once Copilot starts the app: + +1. In the canvas, choose **Connect** beside your app's server. If none is running, choose **Start dev server**. +2. Once the page appears, try its navigation and any included interactions. -Once the page appears, try its navigation and any included interactions. Check the preview itself rather than relying on a setup success message. +> **Note:** Check the preview itself rather than relying on a setup success message. If the page does not appear or reports an error, ask Copilot to investigate using the repository's README and, where present, `SETUP.md` before continuing. @@ -122,13 +151,19 @@ Now that you can try the app, give Copilot the information it needs to build pro If the repository already uses your team's approved guidance, review what is in place and continue to step 6. You do not need to create it again. -Otherwise, run `/setup-skills` in your Copilot conversation. Provide your product documentation, design-system documentation, and any component or token packages your team uses. Share only sources your organization permits you to use. +Otherwise: + +1. Run `/setup-skills` in your Copilot conversation. +2. Provide approved sources: product documentation, design-system documentation, and any component or token packages your team uses. +3. Review the drafts using your team's usual approval process and request any corrections. +4. Once the drafts are reviewed, give Copilot separate approval to apply them. +5. Ask Copilot to confirm which guidance is now in use. Copilot checks those sources and drafts instructions for building prototypes. It asks for permission before installing any packages. -Review the drafts using your team's usual approval process and request any corrections. Once the drafts are reviewed, give Copilot separate approval to apply them. Ask it to confirm which guidance is now in use. +**If setup fails:** Resolve package installation or app errors before continuing. -If a package cannot be installed or the app no longer runs, resolve the reported error before continuing. Without approved guidance, you can still explore the starter, but you have not yet checked whether Replica follows your team's design system. +> **Note:** Without approved guidance, you can still explore the starter, but you have not yet checked whether Replica follows your team's design system. **Ready to continue:** the reviewed guidance is in use and the app still runs. The next step is to try that guidance in a prototype. @@ -147,9 +182,16 @@ Use a separate branch for this prototype. Leave the default branch unchanged. Ask for approval before making any commits. Do not push or publish anything. ``` -The prompt asks Copilot to preserve a reusable starting version before experimenting. A new starter needs its first local commit before a separate prototype branch can keep those versions apart. Copilot must ask for your approval to make that commit; it does not upload or publish anything. For an existing team repository, use its usual review process for changes to the shared starting point. +The prompt asks Copilot to preserve a reusable starting version before experimenting: + +- **New starter:** Its first local commit saves the starting version before work begins on a separate prototype branch. Copilot must ask for approval to make that commit. It does not upload or publish anything. +- **Existing team repository:** Use its usual review process for changes to the shared starting point. -Try the result in the canvas. For the example above, search for a project, try a search with no results, and clear the search. Check that the prototype uses your team's intended components and patterns, then ask Copilot to revise anything that does not match. +Try the result in the canvas: + +1. Test the interactions. For the example above, search for a project, try a search with no results, and clear the search. +2. Check that the prototype uses your team's intended components and patterns. +3. Ask Copilot to revise anything that does not match. Use sample data throughout. Keep production credentials and real customer data out of the prototype. @@ -161,18 +203,30 @@ Keep this repository and the work completed above. You can share a team starting ### Share a team starting point without Hub -Review the app, active guidance, and any starting pages your team will reuse. Confirm the GitHub owner, repository visibility, and access before creating a repository or pushing files. +1. Review the app, active guidance, and any starting pages your team will reuse. +2. Confirm the GitHub owner, repository visibility, and access before creating a repository or pushing files. +3. Share the reviewed starting version using the appropriate path below. + +- **New GitHub repository:** Authorize Copilot to create it or connect an agreed empty repository as `origin`, then push the saved starting version on the intended default branch. Approve any further local commits separately. +- **Existing shared repository:** Use its contribution process to merge the reviewed changes. Preserve its files, remote, and history. -For a new GitHub repository, authorize Copilot to create it or connect an agreed empty repository as `origin`, then push the saved starting version on the intended default branch. Approve any further local commits separately. Keep prototype-specific work on its separate branch. For an existing shared repository, use its contribution process to merge the reviewed changes. Preserve its files, remote, and history. +Keep prototype-specific work on its separate branch. **Ready to share:** the repository's actual default branch on GitHub contains the reviewed app and active guidance. Teammates with repository access can use it locally, even while hosting or Actions approval is pending. This does not publish a Hub preview or enable shared review comments. ### Add hosted publishing and comments -If your team's Hub already shows a successful Build for the repository's reviewed default branch, continue at [step 7: Connect your canvas to Hub](prototype-environment.md#7-connect-your-canvas-to-hub). +Choose where to continue based on what is ready: + +| What is ready | Continue at | +| --- | --- | +| Hub shows a successful Build for the repository's reviewed default branch | [Step 7: Connect your canvas to Hub](prototype-environment.md#7-connect-your-canvas-to-hub). | +| Hub exists, but the repository connection or build workflow needs setup | [Step 6: Connect GitHub and enable builds](prototype-environment.md#6-connect-github-and-enable-builds). Reuse the existing Hub and GitHub App. | +| Hosting is not set up | Check the [hosting requirements](prototype-environment.md#1-check-readiness-before-you-start), then continue at [step 5: Deploy the hub](prototype-environment.md#5-deploy-the-hub) once they are in place. | -If Hub exists but the repository connection or build workflow still needs setup, use [step 6: Connect GitHub and enable builds](prototype-environment.md#6-connect-github-and-enable-builds). Reuse the existing Hub and GitHub App rather than setting them up again. +The repository setup, guidance, and local prototype are already complete. Do not repeat them. -If hosting has not been set up, check the [hosting requirements](prototype-environment.md#1-check-readiness-before-you-start). Once those are in place, continue at [step 5: Deploy the hub](prototype-environment.md#5-deploy-the-hub). The repository setup, guidance, and local prototype are already complete; continue from there without repeating them. +Within hosted step 6, skip completed work: -If you already shared the starting version on GitHub, skip that part of hosted step 6 and continue at [Connect the repository to the GitHub App](prototype-environment.md#connect-the-repository-to-the-github-app). If the App already includes the repository, continue at [Enable the build workflow](prototype-environment.md#enable-the-build-workflow). +- **Starting version already shared on GitHub:** Continue at [Connect the repository to the GitHub App](prototype-environment.md#connect-the-repository-to-the-github-app). +- **App already includes the repository:** Continue at [Enable the build workflow](prototype-environment.md#enable-the-build-workflow). diff --git a/docs/prototype-environment.md b/docs/prototype-environment.md index bfcf8295..6b1b5749 100644 --- a/docs/prototype-environment.md +++ b/docs/prototype-environment.md @@ -2,11 +2,16 @@ Set up Replica so your team can build prototypes with its design system, share them, and collect feedback. This guide walks you through each step, from checking hosting requirements to publishing your first prototype. -If you only want to try Replica locally, follow [Create your first local prototype](local-prototyping.md). If your team already has a connected repository and Hub, follow [Join your team's Replica environment](getting-started.md). +- **Trying Replica locally?** Follow [Create your first local prototype](local-prototyping.md). +- **Joining an existing setup?** Follow [Join your team's Replica environment](getting-started.md) if your team has a connected repository and Hub. Build and test prototypes in your local development environment, then publish them to Hub for your team to review and comment on. Your organization sets up and manages the server for Hub, rather than using a service hosted by GitHub. -Confirm the server, dedicated domain, network access, and GitHub permissions needed for Hub. While hosting is arranged, set up your prototype repository with your team's design-system guidance and build a working prototype locally. Once Hub is running and connected to the repository, publish that prototype and collect comments from your team. +The setup follows this sequence: + +1. Confirm the server, dedicated domain, network access, and GitHub permissions needed for Hub. +2. Set up your prototype repository with your team's design-system guidance and build a working prototype locally while hosting is arranged. +3. Once Hub is running and connected to the repository, publish that prototype and collect comments from your team. You can handle setup yourself or work with your infrastructure and GitHub administrators. The linked guides provide technical details for each step. @@ -25,11 +30,13 @@ Use sample data for prototypes. Do not include passwords or access keys from liv ### If hosting is blocked -You can build your prototype locally while hosting is being arranged. Follow steps 2 through 4 below, and prepare starting pages in step 9 if useful. Once the hosting requirements are in place, continue at step 5 with the same project. +You can keep working while hosting is arranged: -If GitHub approvals are also pending, keep working locally. You can share your code once you have an approved repository, even if the build workflow is still awaiting approval. You'll need the workflow approved and working before you can publish to Hub. +- **Build locally:** Follow steps 2 through 4 below, and prepare starting pages in step 9 if useful. +- **Share reviewed source:** Once you have an approved GitHub repository, follow [Share the reviewed starting version](#share-the-reviewed-starting-version) in step 6. Stop before the GitHub App and build setup, which need Hub. +- **Resume hosted setup:** Once the hosting requirements are in place, continue at step 5 with the same project. -To share the reviewed code while hosting is pending, follow [Share the reviewed starting version](#share-the-reviewed-starting-version) in step 6. Stop before the GitHub App and build setup, which need Hub. +> **Note:** If GitHub approvals are also pending, keep working locally. Sharing source does not require the build workflow, but publishing to Hub does. ## 2. Connect a prototype repository @@ -37,15 +44,27 @@ To share the reviewed code while hosting is pending, follow [Share the reviewed You'll use the **Replica canvas**, a panel in the GitHub Copilot app that shows your running prototype beside your conversation. It is included in the Replica plugin. -If you already have a Replica repository, open it in Copilot and continue at **Install the Replica plugin if needed** below. You don't need to copy the starter files or start again. If the app already works in the canvas, go to step 3. +If you have already completed some setup, continue from there: -If you already built a local prototype with approved guidance, keep that work and continue at step 5 once the hosting requirements are in place. If Hub is already running, continue at step 6 instead. +| What is ready | Continue at | +| --- | --- | +| A Replica repository | Open it in Copilot and continue at **Install the Replica plugin if needed** below. Do not copy the starter again. | +| The app works in the canvas | Step 3. | +| A local prototype with approved guidance | Step 5 once hosting requirements are in place, or step 6 if Hub is already running. Keep your existing work. | ### Prepare your local development environment -If you don't already have the [GitHub Copilot app](https://github.com/features/ai/github-app), install it and sign in. You also need [Git](https://git-scm.com/), [Node.js](https://nodejs.org/), and npm. Use a Node.js version matching `engines.node` in your repository's `package.json`, or [the starter's package.json](../starter/package.json) for a new repository. Reuse a compatible installation. +Check that your local development environment has: + +- **The [GitHub Copilot app](https://github.com/features/ai/github-app)**, installed and signed in. +- **[Git](https://git-scm.com/)**. +- **[Node.js](https://nodejs.org/) and npm**, with a Node.js version matching `engines.node` in your repository's `package.json`, or [the starter's package.json](../starter/package.json) for a new repository. +- **macOS or Linux**, the supported systems for local canvas previews. +- **`lsof`**, which the canvas uses to find running local servers. -The Replica canvas supports local previews on macOS and Linux. It uses `lsof` to find running local servers. Install missing tools through your organization's approved process. The starter installer does not install Node.js or change your shell configuration. +Reuse compatible installations and install missing tools through your organization's approved process. + +> **Note:** The starter installer does not install Node.js or change your shell configuration. Copilot requires GitHub sign-in, but creating the local starter does not require GitHub repository access. You can use a Copilot plan or [connect your own model provider](https://docs.github.com/en/copilot/how-tos/github-copilot-app/use-byok-models). @@ -53,51 +72,60 @@ Copilot requires GitHub sign-in, but creating the local starter does not require The starter provides a working app to build on. The installer creates a new folder for it, named `my-prototype` in the example below. Choose a name that is not already in use. -In a terminal, go to the directory where you want the new folder created, then download the installer: +The new folder is an independent local Git repository. The installer does not create a GitHub repository, commit files, or publish anything. -```sh -curl -fLSs https://raw.githubusercontent.com/github/replica/main/scripts/install-starter.sh -o install-starter.sh -``` +> **Before accepting Copilot setup:** Session setup can install Copilot's command-line tool, the Replica plugin, and project dependencies. -Review the installer, then run it with a name for your new project folder: +1. In a terminal, go to the directory where you want the new folder created, then download the installer: -```sh -bash install-starter.sh my-prototype -``` + ```sh + curl -fLSs https://raw.githubusercontent.com/github/replica/main/scripts/install-starter.sh -o install-starter.sh + ``` -This creates `my-prototype` as an independent local Git repository. It does not create a GitHub repository, commit files, or publish anything. +2. Review the installer, then run it with a name for your new project folder: -In Copilot, choose **Projects → + → Local folder or repository** and add the new folder. Before accepting its setup settings, review `.github/github-app.yml` and the copied README. Setup can install Copilot's command-line tool, the Replica plugin, and project dependencies. + ```sh + bash install-starter.sh my-prototype + ``` -Start a fresh session in the new repository so Copilot can find its included skills. If another session created the folder, give the new session a summary of completed setup and what you want to build. +3. In Copilot, choose **Projects → + → Local folder or repository** and add the new folder. +4. Before accepting its setup settings, review `.github/github-app.yml` and the copied README. +5. Start a fresh session in the new repository so Copilot can find its included skills. If another session created the folder, give the new session a summary of completed setup and what you want to build. ### Install the Replica plugin if needed If the Replica plugin appears under **Customize → Installed**, continue at **Open the app in the canvas** below. -The Replica starter installs the plugin during session setup. It checks for Copilot CLI and installs it if missing. Check the session setup output for dependency or plugin failures. If setup failed, resolve the reported error, then run `node scripts/setup-replica-plugin.mjs` from the repository folder to retry plugin setup. +The Replica starter installs the plugin during session setup. It checks for Copilot CLI and installs it if missing. -For repositories without that setup script, use the manual plugin commands below. These require the `copilot` command in your terminal. Check with `copilot --version`; if the command is not found, follow the [Copilot CLI installation instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli) before continuing. +- **If starter setup failed:** Check the session setup output, resolve the reported dependency or plugin error, then run `node scripts/setup-replica-plugin.mjs` from the repository folder to retry plugin setup. +- **If your repository has no setup script:** Use the manual installation steps below. -These commands install Replica from its default branch. If your organization requires a specific version or source, use its installation instructions instead. +> **Before installing manually:** These commands install Replica from its default branch. If your organization requires a specific version or source, use its installation instructions instead. -First, add Replica's plugin marketplace if you haven't already: +For manual installation: -```sh -copilot plugin marketplace add github/replica -``` +1. Check that `copilot` is available in your terminal with `copilot --version`. If it is not found, follow the [Copilot CLI installation instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli). +2. Add Replica's plugin marketplace if you haven't already: -Then install the Replica plugin: + ```sh + copilot plugin marketplace add github/replica + ``` -```sh -copilot plugin install replica-prototype@replica -``` +3. Install the Replica plugin: + + ```sh + copilot plugin install replica-prototype@replica + ``` ### Open the app in the canvas -With the plugin installed, enable the canvas and try the app before making changes. In Copilot, open **Customize → Installed** and enable both the Replica plugin and its canvas extension. They are separate switches. +With the plugin installed, enable the canvas and try the app before making changes: -Start a fresh session after installation or enablement, then choose **+ → Canvas → Replica prototype**. Keep only one copy of the Replica canvas enabled. +1. In Copilot, open **Customize → Installed**. +2. Enable both the Replica plugin and its canvas extension. They are separate switches. +3. Start a fresh session after installation or enablement. +4. Choose **+ → Canvas → Replica prototype**. Keep only one copy of the Replica canvas enabled. Ask Copilot: @@ -107,9 +135,19 @@ Use the run commands in its README and the URL printed by the server. Do not change the app, connect to Hub, or publish anything yet. ``` -If the canvas lists running servers, choose **Connect** beside your app's server. If none is running, choose **Start dev server**. Once the page appears, try its navigation and any included interactions. Installing dependencies or completing `/setup-skills` does not confirm that the preview works. +Once Copilot starts the app: + +1. In the canvas, choose **Connect** beside your app's server. If none is running, choose **Start dev server**. +2. Once the page appears, try its navigation and any included interactions. + +> **Note:** Installing dependencies or completing `/setup-skills` does not confirm that the preview works. -If installation fails, use the error and recovery instructions in the terminal or session setup output. Resolve policy or permission errors through your organization's approval process rather than bypassing them. If the canvas is missing, confirm both switches are enabled and start a fresh session after changing them. For preview errors, ask Copilot to investigate using the repository's README and, where present, `SETUP.md` before continuing. +**If setup fails:** + +- **Installation failure:** Use the error and recovery instructions in the terminal or session setup output. +- **Policy or permission error:** Resolve it through your organization's approval process rather than bypassing it. +- **Missing canvas:** Confirm both switches are enabled and start a fresh session after changing them. +- **Preview error:** Ask Copilot to investigate using the repository's README and, where present, `SETUP.md` before continuing. **Ready to continue:** the app works in your canvas. You have not connected to Hub or published anything. @@ -119,11 +157,19 @@ Give Copilot the information it needs to build prototypes that follow your team' If the repository already uses your team's approved guidance, review what is in place and continue to step 4. You do not need to create it again. -Otherwise, run `/setup-skills` in your prototype session. Share approved product documentation, design-system guidance, and any component packages your team uses. +Otherwise: + +1. Run `/setup-skills` in your prototype session. +2. Share approved sources: product documentation, design-system guidance, and any component packages your team uses. +3. Review the drafts using your team's usual approval process and request any corrections. +4. Once the drafts are reviewed, give Copilot separate approval to apply them. +5. Ask Copilot to confirm which guidance is now in use. + +Copilot drafts instructions from those sources and asks permission before installing packages. -Copilot drafts instructions from those sources and asks permission before installing packages. Review the drafts using your team's usual approval process and request any corrections. Once the drafts are reviewed, give Copilot separate approval to apply them. Ask it to confirm which guidance is now in use. +**If setup fails:** Resolve package installation or build errors before continuing. -You do not need to connect Hub to complete this step. Resolve any package installation or build errors before continuing. +> **Note:** You do not need to connect Hub to complete this step. ## 4. Build a useful first prototype @@ -140,7 +186,10 @@ Use a separate branch for this prototype. Leave the default branch unchanged. Ask for approval before making any commits. Do not push or publish anything. ``` -The prompt asks Copilot to preserve a reusable starting version before experimenting. A new starter needs its first local commit before a separate prototype branch can keep those versions apart. Copilot must ask for your approval to make that commit; it does not upload or publish anything. For an existing team repository, use its usual review process for changes to the shared starting point. +The prompt asks Copilot to preserve a reusable starting version before experimenting: + +- **New starter:** Its first local commit saves the starting version before work begins on a separate prototype branch. Copilot must ask for approval to make that commit. It does not upload or publish anything. +- **Existing team repository:** Use its usual review process for changes to the shared starting point. Try the interactions and confirm that the prototype uses your team's components. @@ -150,15 +199,24 @@ Try the interactions and confirm that the prototype uses your team's components. If Hub is already running, reuse it and continue at step 6. You do not need to deploy another Hub. -Follow the [Hub deployment guide](../hub/docs/deployment.md) on the Hub server, or share it with the person handling deployment. This can happen alongside steps 2 through 4. Use the released installation package, not the developer setup. +Deployment can happen alongside steps 2 through 4. Follow the [Hub deployment guide](../hub/docs/deployment.md) on the Hub server, or share it with the person handling deployment. + +**Keep the deployment settings safe:** -Deployment includes downloading and checking the installation files, creating Hub's settings, setting up DNS and HTTPS, and starting Hub. The `./replica init` command creates settings; it does not complete all these steps. +- Store the private settings file (`.env`) securely and never add it to a Git repository. +- Do not run `./replica init` again on an existing installation. +- Keep the original security keys. New keys cannot read the saved GitHub connection details. -Keep the Hub web address and the setup code printed during installation for step 6. Store the private settings file (`.env`) securely and never add it to a Git repository. Do not run `./replica init` again on an existing installation. Keep the original security keys; new keys cannot read the saved GitHub connection details. +Using the released installation package, not the developer setup: -Check the [web forwarding settings](../hub/docs/deployment.md#client-ip-addresses-and-trusted-proxies) and arrange [backups and recovery](../hub/docs/backups-and-restore.md) before the wider team joins. +1. Download and check the installation files, create Hub's settings, set up DNS and HTTPS, and start Hub as described in the deployment guide. +2. Keep the Hub web address and the setup code printed during installation for step 6. +3. Check the [web forwarding settings](../hub/docs/deployment.md#client-ip-addresses-and-trusted-proxies) and arrange [backups and recovery](../hub/docs/backups-and-restore.md) before the wider team joins. +4. Open the setup page at your Hub address, such as `https://hub.example.com/setup`. -Open the setup page at your Hub address, such as `https://hub.example.com/setup`. If it does not open, run `./replica logs` on the Hub server and follow the [startup troubleshooting instructions](../hub/docs/deployment.md#troubleshoot-startup). +> **Note:** The `./replica init` command creates settings; it does not complete deployment. + +**If the setup page does not open:** Run `./replica logs` on the Hub server and follow the [startup troubleshooting instructions](../hub/docs/deployment.md#troubleshoot-startup). **Ready to continue:** the setup page opens, and DNS and HTTPS are configured for both Hub and its previews. Publishing is not tested yet. @@ -168,56 +226,81 @@ With Hub running, connect the repository and enable its build workflow. If Hub a ### Share the reviewed starting version -If your project is not on GitHub yet, agree which organization will own the repository and whether it should be private or public. Give prototype authors write access and reviewers read access. - If the reviewed app and approved guidance are already on GitHub's default branch, reuse that version and continue at **Connect the repository to the GitHub App** below. -Otherwise, ask Copilot to connect the agreed GitHub repository and upload the saved starting version to its intended default branch. Approve any repository creation, commits, and uploads before they proceed. Keep your prototype on its own branch. For an existing shared repository, use its usual review process; do not replace its files, remote, or history. +1. If your project is not on GitHub yet, agree which organization will own the repository and whether it should be private or public. +2. Give prototype authors write access and reviewers read access. +3. Ask Copilot to connect the agreed GitHub repository and upload the saved starting version to its intended default branch. Approve any repository creation, commits, and uploads before they proceed. + +> **Note:** Keep your prototype on its own branch. For an existing shared repository, use its usual review process; do not replace its files, remote, or history. ### Connect the repository to the GitHub App -Check the [prototype requirements](../hub/docs/github-actions-builds.md#prototype-requirements) before connecting the repository. +**Access rules:** -For a new Hub, open its `/setup` page and enter the setup code from step 5. Follow the [GitHub App setup instructions](../hub/docs/github-app-setup.md#setup) to create a private App owned by your organization and install it on the prototype repository. +- Keep the App private and organization-owned. An App created under a personal account would only let that person sign in. +- Before connecting a public repository, review [who will be able to access its reviews](../hub/docs/authentication-and-repository-authorization.md#app-ownership-and-repository-visibility). +- Creating the App does not automatically make anyone a Hub administrator. -For an existing Hub, reuse its GitHub App and include this repository in the App's installation on GitHub. If the repository is already included, no installation change is needed. Do not repeat Hub's initial setup. +1. Check the [prototype requirements](../hub/docs/github-actions-builds.md#prototype-requirements) before connecting the repository. +2. Connect the repository using the path for your Hub: -Do not create the App under a personal account for a team environment: only that person would be able to sign in. Keep the App private. Before connecting a public repository, review [who will be able to access its reviews](../hub/docs/authentication-and-repository-authorization.md#app-ownership-and-repository-visibility). + | Hub setup | Action | + | --- | --- | + | New Hub | Open `/setup` and enter the setup code from step 5. Follow the [GitHub App setup instructions](../hub/docs/github-app-setup.md#setup) to create a private App owned by your organization and install it on the prototype repository. | + | Existing Hub | Reuse its GitHub App and include this repository in the App's installation on GitHub. If it is already included, no installation change is needed. Do not repeat initial setup. | -If Hub does not have an administrator yet, the person who will look after it must [register as a Hub administrator](../hub/docs/security-audit.md#enroll-an-operator). Creating the App does not give them that role automatically. +3. If Hub does not have an administrator yet, have the person who will look after it [register as a Hub administrator](../hub/docs/security-audit.md#enroll-an-operator). ### Enable the build workflow -Sign in to Hub with a GitHub account that has write access to the repository. If the Replica build workflow is already installed, check its latest default-branch Build instead of installing it again. If it needs updating, follow the [workflow installation instructions](../hub/docs/github-actions-builds.md#install-the-repository-workflow). +The workflow prepares your app for publishing. Hub downloads the result and calls each prepared version a **Build**. -If the workflow is not installed, open the repository in Hub and choose **Open installation pull request**. This proposes a GitHub Actions workflow that prepares your app for publishing. Review and merge it using your team's usual review process and the workflow installation instructions above. +1. Sign in to Hub with a GitHub account that has write access to the repository. +2. Check the workflow's status: -Wait for the workflow to finish and for Hub to download the result. Hub calls each prepared version a **Build**. If the workflow fails or a download is denied, investigate the displayed error. + | Workflow status | Action | + | --- | --- | + | Already installed | Check its latest default-branch Build rather than installing it again. If it needs updating, follow the [workflow installation instructions](../hub/docs/github-actions-builds.md#install-the-repository-workflow). | + | Not installed | Open the repository in Hub and choose **Open installation pull request**. Review and merge it using your team's usual review process and the workflow installation instructions. | -**Ready to continue:** Hub shows a successful Build for the repository's default branch. A successful GitHub workflow alone is not enough. +3. Wait for the workflow to finish and for Hub to download the result. -## 7. Connect your canvas to Hub +**If the workflow fails or a download is denied:** Investigate the displayed error before continuing. -Install [GitHub CLI](https://cli.github.com/) on your computer if needed. Sign in with an account that can access the repository. Copilot sign-in does not sign you in to GitHub CLI. +**Ready to continue:** Hub shows a successful Build for the repository's default branch. A successful GitHub workflow alone is not enough. -[Save your team's Hub address in the repository](../starter/README.md#connect-to-hub), in `.github/replica.json`. Keep any existing settings in that file. Review and merge the change into the default branch so teammates can use it too. +## 7. Connect your canvas to Hub -Saving the address does not grant access. Each person must still approve their own connection to Hub. +1. Install [GitHub CLI](https://cli.github.com/) on your computer if needed, then sign in with an account that can access the repository. +2. [Save your team's Hub address](../starter/README.md#connect-to-hub) in the repository's `.github/replica.json`. Keep any existing settings. +3. Review and merge the change into the default branch so teammates can use it too. +4. Open your prototype session and its canvas. If the app is not running, ask Copilot to start it and show it in the canvas. +5. Choose **Connect to the hub** and enter your team's Hub URL if asked. +6. In the browser, check the Hub address, repository, and approval code. Approve only if they match what the canvas shows. -Open your prototype session and its canvas. If the app is not running, ask Copilot to start it and show it in the canvas. +> **Note:** Copilot sign-in does not sign you in to GitHub CLI. Saving the Hub address does not grant access; each person must approve their own connection. -Choose **Connect to the hub** and enter your team's Hub URL if asked. In the browser, check the Hub address, repository, and approval code. Approve only if they match what the canvas shows. +**If the connection is wrong or fails:** -If the canvas points to a different Hub, follow the [Hub switching instructions](../hub/docs/prototype-canvas.md#repository-hub-discovery). For approval problems, see [connection approval](../hub/docs/prototype-canvas.md#pairing-and-review). +- **Wrong Hub:** Follow the [Hub switching instructions](../hub/docs/prototype-canvas.md#repository-hub-discovery). +- **Approval problem:** See [connection approval](../hub/docs/prototype-canvas.md#pairing-and-review). **Ready to continue:** you can use the app in the canvas and have approved its connection to your team's Hub. Connecting does not publish anything. ## 8. Publish your prototype and exchange feedback -Share the prototype you built with your team's guidance: +Before publishing: + +1. Open your prototype session. +2. Ask Copilot to confirm that you are on the prototype's branch, not the default branch, and that it includes `.github/workflows/replica.yml` from step 6. +3. If the workflow is missing, ask Copilot to preserve your local prototype work and, with your approval, fetch and merge the reviewed default-branch changes into this branch. Resolve any conflicts before continuing. +4. Check the result in the canvas. -1. Open your prototype session. Ask Copilot to confirm that you are on the prototype's branch, not the default branch, and that it includes `.github/workflows/replica.yml` from step 6. If the workflow is missing, ask Copilot to preserve your local prototype work and, with your approval, fetch and merge the reviewed default-branch changes into this branch. Resolve any conflicts before continuing. Check the result in the canvas. -2. Choose **Publish** and approve saving and uploading your prototype changes. Wait until the canvas says **Published**. A completed upload alone does not mean Hub is ready to show it. +Then publish and exchange feedback: + +1. Choose **Publish** and approve saving and uploading your prototype changes. +2. Wait until the canvas says **Published**. A completed upload alone does not mean Hub is ready to show it. 3. Open **Share prototype**, copy the **Internal prototype link**, and send it to your teammate. 4. Ask them to sign in, open the prototype, and leave a comment. They need at least read access to the repository. 5. Check that you can read their comment in your connected canvas. @@ -230,28 +313,37 @@ Use the internal link for this first review. Public sharing is off by default an ## 9. Prepare useful starting pages -Create a few pages your teammates can use as starting points. For example, a list, a detail page, and an empty state might help them try common product ideas. Use sample data. - -You can prepare these pages before Hub is ready. If you already have them, review and reuse them rather than creating them again. +Starting pages help teammates try common product ideas. For example, you might offer a list, a detail page, and an empty state. Hub already offers **Default**, which opens your app's main page. -Hub already offers **Default**, which opens your app's main page. To offer other starting pages, add them to `.github/replica.json` using the [template instructions](../hub/docs/github-actions-builds.md#uploaded-artifact). Keep the Hub address you added earlier in that file. +1. Create a few starting pages using sample data, or review and reuse pages you already have. +2. Add them to `.github/replica.json` using the [template instructions](../hub/docs/github-actions-builds.md#uploaded-artifact). Keep the Hub address you added earlier in that file. +3. Review the guidance and pages together. +4. Have the approved changes merged into the default branch using your team's usual review process. +5. Wait for the updated Build to appear in Hub, then check that the **Templates** list shows the starting pages you expect. -Review the guidance and pages together. Have the approved changes merged into the default branch using your team's usual review process. Wait for the updated Build to appear in Hub, then check that the **Templates** list shows the starting pages you expect. +> **Note:** You can prepare the pages before Hub is ready. Check their appearance in the Templates list once Hub is running. **Ready to continue:** your team's shared version has approved guidance and working starting pages. New prototypes can use that version without changing it. ## 10. Invite the team -Ask someone who did not help with setup to follow [Join your team's Replica environment](getting-started.md). Check that they can create a prototype using the approved guidance, publish it, and exchange feedback. +1. Ask someone who did not help with setup to follow [Join your team's Replica environment](getting-started.md). +2. Check that they can create a prototype using the approved guidance, publish it, and exchange feedback. +3. Share the setup details with the team: -Share the repository link, Hub URL, and joining guide with the team. Include any required tool or plugin versions. Tell them who to ask about the design guidance, starting pages, and Hub itself. + | Detail | What to include | + | --- | --- | + | Getting started | Repository link, Hub URL, and joining guide. | + | Tooling | Any required tool or plugin versions. | + | Support | Who to ask about the design guidance, starting pages, and Hub. | -They should use your existing repository and Hub, not install another starter or set up another server. +> **Note:** Teammates should use your existing repository and Hub, not install another starter or set up another server. ## 11. Maintain the shared environment -Keep the guidance and starting pages up to date. Review changes before adding them to the default branch for everyone to use. - -The person running Hub should follow the [maintenance instructions](../hub/docs/deployment.md#operate-the-deployment) to check that it is working, investigate problems, and install updates. Keep the existing security keys and saved data when updating, and maintain the agreed backups. +The people looking after the shared environment handle ongoing maintenance. Each prototype user does not need to repeat these tasks. -Review who has access and who will restore Hub if something goes wrong. If your organization enables public sharing, also review shared links and their expiration dates. The people looking after Hub handle these tasks; each prototype author does not need to repeat them. +- **Guidance and pages:** Keep them up to date and review changes before adding them to the default branch for everyone to use. +- **Hub operation:** Follow the [maintenance instructions](../hub/docs/deployment.md#operate-the-deployment) to check that it is working, investigate problems, and install updates. +- **Recovery:** Keep the existing security keys and saved data when updating, maintain the agreed backups, and confirm who will restore Hub if something goes wrong. +- **Access:** Review who has access. If your organization enables public sharing, also review shared links and their expiration dates. From 4bac279d8466c75a4b35824c7ad8d9d51586c405 Mon Sep 17 00:00:00 2001 From: Catharine McNally <2089974+cmcnally@users.noreply.github.com> Date: Tue, 27 Oct 2026 07:17:32 -0700 Subject: [PATCH 6/6] docs: explain starter choices in plain language Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 045ed8e1-41ea-44f3-a2c6-d9f485f87ca1 --- README.md | 9 +++++++-- docs/local-prototyping.md | 8 +++++--- docs/prototype-environment.md | 10 ++++++---- 3 files changed, 18 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 6cbbc430..6f941101 100644 --- a/README.md +++ b/README.md @@ -57,12 +57,17 @@ If hosting is blocked, you can work locally and connect the same repository late | Part | What it does | | --- | --- | -| **Starters** | Create a local prototype project from your choice of app, with shared skills for Copilot. | +| **Starters** | Ready-made apps to build your prototype from, with shared skills for Copilot. | | **Replica plugin** | Adds the Replica canvas to Copilot, showing your running prototype beside your conversation. | | **Replica Hub (optional)** | Hosts published prototypes so your team can try them and leave comments. | | **GitHub build action** | Builds prototypes for publishing to Hub. It is not needed for local prototyping. | -For a new repository, choose **Minimal**, a small React app with no component library, or **CoreAI Sandbox**, a React Router app with CoreAI components and a Foundry-style shell. Agents creating or adapting repositories should follow [prototype repository setup](docs/prototype-repository-setup.md). +For a new repository, choose a starter: + +- **Minimal:** A small example app to adapt to your own design system. +- **CoreAI Sandbox:** An app with an existing navigation layout and prebuilt interface elements, such as buttons and menus, from Microsoft's CoreAI design system. + +Agents creating or adapting repositories should follow [prototype repository setup](docs/prototype-repository-setup.md). ## Data and privacy diff --git a/docs/local-prototyping.md b/docs/local-prototyping.md index 3791aa6a..dc339520 100644 --- a/docs/local-prototyping.md +++ b/docs/local-prototyping.md @@ -36,6 +36,8 @@ If you already have a Replica repository, use **Open an existing repository** be ### Create a repository from the starter +A starter is a ready-made app to build your prototype from. Choose **Minimal** for a small example app to adapt to your own design system, or **CoreAI Sandbox** for an app with an existing layout and Microsoft's CoreAI design system. + The installer creates a new folder for your prototype, named `my-prototype` in the example below. Choose a name that is not already in use. The new folder is an independent local Git repository with the copied files saved in an initial commit on `main`. The installer does not create a GitHub repository, set a remote, or publish anything. @@ -56,10 +58,10 @@ The new folder is an independent local Git repository with the copied files save 3. Choose an app from the [starter catalog](../starters/catalog.tsv): - | App | Starting point | + | Starter | Choose it when | | --- | --- | - | **Minimal** (`minimal`) | A small React app with TanStack Router and no component library. | - | **CoreAI Sandbox** (`coreai`) | A React Router app with CoreAI components and a Foundry-style shell. | + | **Minimal** (`minimal`) | You want a small example app to adapt to your own design system. | + | **CoreAI Sandbox** (`coreai`) | You want an existing navigation layout and prebuilt interface elements, such as buttons and menus, from Microsoft's CoreAI design system. | 4. Run the installer with your choice and new folder name. This example selects Minimal; replace `minimal` with your chosen catalog ID: diff --git a/docs/prototype-environment.md b/docs/prototype-environment.md index f45ac3ca..a243b8e3 100644 --- a/docs/prototype-environment.md +++ b/docs/prototype-environment.md @@ -71,7 +71,9 @@ Copilot requires GitHub sign-in, but creating the local starter does not require ### Create a starter if you need one -Choose an app to build on. The installer creates a new folder for it, named `my-prototype` in the example below. Choose a name that is not already in use. +A starter is a ready-made app to build your prototype from. Choose **Minimal** for a small example app to adapt to your own design system, or **CoreAI Sandbox** for an app with an existing layout and Microsoft's CoreAI design system. + +The installer creates a new folder for it, named `my-prototype` in the example below. Choose a name that is not already in use. The new folder is an independent local Git repository with the copied files saved in an initial commit on `main`. The installer does not create a GitHub repository, set a remote, or publish anything. @@ -91,10 +93,10 @@ The new folder is an independent local Git repository with the copied files save 3. Choose an app from the [starter catalog](../starters/catalog.tsv): - | App | Starting point | + | Starter | Choose it when | | --- | --- | - | **Minimal** (`minimal`) | A small React app with TanStack Router and no component library. | - | **CoreAI Sandbox** (`coreai`) | A React Router app with CoreAI components and a Foundry-style shell. | + | **Minimal** (`minimal`) | You want a small example app to adapt to your own design system. | + | **CoreAI Sandbox** (`coreai`) | You want an existing navigation layout and prebuilt interface elements, such as buttons and menus, from Microsoft's CoreAI design system. | 4. Run the installer with your choice and new folder name. This example selects Minimal; replace `minimal` with your chosen catalog ID: