diff --git a/README.md b/README.md index c6ee1a45..6f941101 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 | | --- | --- | -| **Starters** | Create a local prototype project from your choice of app, with shared agent skills. | -| **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?** 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. Point your agent at [prototype repository setup](docs/prototype-repository-setup.md) to select an app, create the repository and verify its local preview. 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,22 @@ 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 | +| --- | --- | +| **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 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 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 9d4a9547..bb473ad2 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 f4057315..13110c66 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,30 +1,45 @@ -# 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 -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: @@ -35,33 +50,56 @@ 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 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: -You can also run this manually in a terminal with Copilot CLI available. + ```sh + copilot plugin marketplace add github/replica + ``` -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. +3. Install the plugin: -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. + ```sh + copilot plugin install replica-prototype@replica + ``` -Start a fresh session in the Copilot app, then select **+ → Canvas → Replica prototype**. +### Enable the plugin and canvas + +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 **+** 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. +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 @@ -71,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#4-deploy-the-hub). +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 @@ -120,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 @@ -139,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 [shared Controls guide](../starters/shared/REPLICA.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 [shared Controls guide](../starters/shared/REPLICA.md#prototype-controls) covers authoring and recovery. diff --git a/docs/local-prototyping.md b/docs/local-prototyping.md new file mode 100644 index 00000000..dc339520 --- /dev/null +++ b/docs/local-prototyping.md @@ -0,0 +1,252 @@ +# 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. + +- **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 + +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/)**, with `user.name` and `user.email` configured for the installer's initial local commit. +- **[Node.js](https://nodejs.org/) and npm**, with a Node.js version matching `engines.node` in your repository's `package.json`, or the selected app's `package.json` in the [starter catalog](../starters/catalog.tsv) for a new repository. npm comes with Node.js. +- **Bash, curl, and tar**, for downloading and running the starter installer. +- **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). + +## 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 + +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. + +> **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`. + +1. 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 + ``` + +2. Review the installer, then list the available apps: + + ```sh + bash install-starter.sh --list + ``` + +3. Choose an app from the [starter catalog](../starters/catalog.tsv): + + | Starter | Choose it when | + | --- | --- | + | **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: + + ```sh + bash install-starter.sh --starter minimal my-prototype + ``` + +5. In Copilot, choose **Sessions → + → Open folder** and open the new folder. +6. Before accepting its repository configuration, review `.github/github-app.yml` and the copied `REPLICA.md`. +7. 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, the chosen app, and what you want to build. + +> **If creation fails:** Resolve the reported Git identity, signing, or hook error before retrying. The installer uses your existing Git configuration without changing it and removes an incomplete destination if the initial commit fails. + +The app's README explains its examples and run commands. The shared [Replica workflow guide](../starters/shared/REPLICA.md) and [troubleshooting guide](../starters/shared/SETUP.md) are copied into every repository. + +Continue at step 3. + +### Open an existing repository + +1. Choose the repository from **Projects** in Copilot. If it is not listed, add it using one of these options: + + | 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. + +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 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. + +> **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. + +For manual installation: + +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: + + ```sh + copilot plugin marketplace add github/replica + ``` + +3. Install the Replica plugin: + + ```sh + copilot plugin install replica-prototype@replica + ``` + +### Activate the plugin and canvas + +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. + +**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. + +**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. +``` + +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:** 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, `REPLICA.md`, and `SETUP.md` where present 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. + +Review the selected app's supplied guidance first. Preserve its skills and active context. If the repository already uses your team's approved guidance, continue to step 6. You do not need to create it again. + +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. + +**If setup fails:** Resolve package installation or app errors before continuing. + +> **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. + +## 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 guidance or starting pages changed after setup, ask for my approval +to save those changes in a local commit before creating the prototype 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: + +- **New starter:** The installer has already saved the copied files in an initial local commit. Approve a separate commit for any reviewed guidance or starting-page changes before experimenting. Neither local commit uploads or publishes anything. +- **Existing team repository:** Use its usual review process for changes to the shared starting point. + +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. + +**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 + +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. + +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 + +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. | + +The repository setup, guidance, and local prototype are already complete. Do not repeat them. + +Within hosted step 6, skip completed work: + +- **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 b33b22a1..a243b8e3 100644 --- a/docs/prototype-environment.md +++ b/docs/prototype-environment.md @@ -1,137 +1,369 @@ -# 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. +- **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. -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. +The setup follows this sequence: -## Who should be involved +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. -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. +You can handle setup yourself or work with your infrastructure and GitHub administrators. The linked guides provide technical details for each step. -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. +## 1. Check readiness before you start -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 the selected app's `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. +Before setting up Hub, confirm what is available, what needs approval, and who will handle any remaining setup. -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. +- **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. -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. +Use sample data for prototypes. Do not include passwords or access keys from live systems, or real customer data. -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. +**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. -## 1. Create the team's prototype repository +### If hosting is blocked -Follow steps 1 through 3 of [prototype repository setup](prototype-repository-setup.md) to choose an app from the catalog, create an independent repository, open a fresh Copilot session and verify its local preview. Then return here to prepare the team's guidance and starting pages. +You can keep working while hosting is arranged: -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. +- **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. -## 2. Add your product and design-system guidance +> **Note:** If GitHub approvals are also pending, keep working locally. Sharing source does not require the build workflow, but publishing to Hub does. -Review the selected app's supplied guidance first. Run `/setup-skills` when the team's product or design-system guidance must be added or changed. 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. +## 2. Connect a prototype repository -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 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. -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. +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. -The selected app's README explains its examples and commands. The shared [Replica workflow guide](../starters/shared/REPLICA.md) and [troubleshooting guide](../starters/shared/SETUP.md) are copied into every repository and cover canvas integration and installation errors. +If you have already completed some setup, continue from there: -## 3. Prepare useful starting pages +| 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. | -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. +### Prepare your local development environment -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. +Check that your local development environment has: -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. +- **The [GitHub Copilot app](https://github.com/features/ai/github-app)**, installed and signed in. +- **[Git](https://git-scm.com/)**, with `user.name` and `user.email` configured for the installer's initial local commit. +- **[Node.js](https://nodejs.org/) and npm**, with a Node.js version matching `engines.node` in your repository's `package.json`, or the selected app's `package.json` in the [starter catalog](../starters/catalog.tsv) for a new repository. npm comes with Node.js. +- **Bash, curl, and tar**, for downloading and running the starter installer. +- **macOS or Linux**, the supported systems for local canvas previews. +- **`lsof`**, which the canvas uses to find running local servers. -## 4. Deploy the hub +Reuse compatible installations and install missing tools through your organization's approved process. -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. +> **Note:** The starter installer does not install Node.js or change your shell configuration. -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. +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). -### Download and initialize the container deployment +### Create a starter if you need one -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. +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. -From the extracted deployment directory, run: +The installer creates a new folder for it, named `my-prototype` in the example below. Choose a name that is not already in use. -```sh -./replica init -``` +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. + +> **Before accepting Copilot setup:** Session setup can install Copilot's command-line tool, the Replica plugin, and project dependencies. + +1. 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 + ``` + +2. Review the installer, then list the available apps: + + ```sh + bash install-starter.sh --list + ``` + +3. Choose an app from the [starter catalog](../starters/catalog.tsv): + + | Starter | Choose it when | + | --- | --- | + | **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: + + ```sh + bash install-starter.sh --starter minimal my-prototype + ``` + +5. In Copilot, choose **Sessions → + → Open folder** and open the new folder. +6. Before accepting its setup settings, review `.github/github-app.yml` and the copied `REPLICA.md`. +7. 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, the chosen app, and what you want to build. + +> **If creation fails:** Resolve the reported Git identity, signing, or hook error before retrying. The installer uses your existing Git configuration without changing it and removes an incomplete destination if the initial commit fails. + +The app's README explains its examples and run commands. The shared [Replica workflow guide](../starters/shared/REPLICA.md) and [troubleshooting guide](../starters/shared/SETUP.md) are copied into every repository. + +### 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. + +- **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. + +> **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. -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. +For manual installation: -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. +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: -### Configure DNS and HTTPS + ```sh + copilot plugin marketplace add github/replica + ``` -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. +3. Install the Replica plugin: -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. + ```sh + copilot plugin install replica-prototype@replica + ``` -### Start Hub and protect its data +### Open the app in the canvas -From the same deployment directory, run: +With the plugin installed, enable the canvas and try the app before making changes: -```sh -./replica up -./replica status +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: + +```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. +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 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, `REPLICA.md`, and `SETUP.md` where present before continuing. + +**Ready to continue:** the app works in your canvas. You have not connected to Hub or published anything. + +## 3. Add your product and design-system guidance + +Give Copilot the information it needs to build prototypes that follow your team's product and design system. -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. +Review the selected app's supplied guidance first. Preserve its skills and active context. If the repository already uses your team's approved guidance, continue to step 4. You do not need to create it again. -## 5. Connect the repository and enable builds +Otherwise: -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. +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. -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. +Copilot drafts instructions from those sources and asks permission before installing packages. -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 setup fails:** Resolve package installation or build errors before continuing. -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. +> **Note:** You do not need to connect Hub to complete this step. -## 6. Connect the Replica prototype canvas +## 4. Build a useful first prototype -Set your team's Hub URL in `.github/replica.json` in the prototype repository so authors do not have to enter it manually: +Choose a small task your team wants to explore. Ask Copilot to build it using the approved guidance and sample data. For example: -```json -{ - "version": 1, - "hub": { - "origin": "https://hub.example.com" - } -} +```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 guidance or starting pages changed after setup, ask for my approval +to save those changes in a local commit before creating the prototype 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: + +- **New starter:** The installer has already saved the copied files in an initial local commit. Approve a separate commit for any reviewed guidance or starting-page changes before experimenting. Neither local commit uploads or publishes 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. + +**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. + +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:** + +- 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: + +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`. + +> **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. + +## 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 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. + +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 + +**Access rules:** + +- 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. + +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: + + | 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. | + +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 + +The workflow prepares your app for publishing. Hub downloads the result and calls each prepared version a **Build**. + +1. Sign in to Hub with a GitHub account that has write access to the repository. +2. Check the workflow's status: + + | 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. | + +3. Wait for the workflow to finish and for Hub to download the result. + +**If the workflow fails or a download is denied:** Investigate the displayed error before continuing. + +**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 + +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](../starters/shared/REPLICA.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. + +> **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. + +**If the connection is wrong or fails:** + +- **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 + +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. + +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. + +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). -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. +**Ready to continue:** your teammate can open the published prototype and leave a comment, and you can read that comment in the canvas. -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. +## 9. Prepare useful starting pages -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. +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. -Keep only one copy of the canvas enabled in a session. +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. -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). +> **Note:** You can prepare the pages before Hub is ready. Check their appearance in the Templates list once Hub is running. -## 7. Try the whole flow before inviting the team +**Ready to continue:** your team's shared version has approved guidance and working starting pages. New prototypes can use that version without changing it. -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. +## 10. Invite the team -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. +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: -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. + | 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. | -## 8. Maintain the shared environment +> **Note:** Teammates should use your existing repository and Hub, not install another starter or set up another server. -Keep product guidance and starting pages current on the repository's default branch. Review and approve guidance changes before asking authors to use them. +## 11. Maintain the shared environment -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 people looking after the shared environment handle ongoing maintenance. Each prototype user does not need to repeat these tasks. -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. +- **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. diff --git a/docs/prototype-repository-setup.md b/docs/prototype-repository-setup.md index 9e480f13..9d65646a 100644 --- a/docs/prototype-repository-setup.md +++ b/docs/prototype-repository-setup.md @@ -1,23 +1,29 @@ # 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. -Choose a starter at creation time. Each app keeps its own routing, dependencies, examples and design-system guidance. Selection does not switch the design system of an existing app. +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 +Choose a starter at creation time. Each app keeps its own routing, dependencies, examples, and design-system guidance. Selection does not switch the design system of an existing app. -Reuse the repository name, destination, starter choice, references, and decisions already supplied. Ask only for missing information needed for the next action. +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. -| Target | Next action | +## 1. Confirm the repository and goal + +Use the repository name, destination, starter choice, 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. Starter creation includes an initial local commit. If the user also requests a GitHub repository, resolve its owner and visibility before creating it. Follow the host's authorization rules for remote repository creation and pushes; local setup alone does not authorize publication. +A local repository needs no GitHub credentials or Hub. Explain that starter creation includes an initial local commit. If the user also requests a GitHub repository, confirm its owner and visibility before creating it. Follow the host's authorization rules for remote repository creation, further commits, and pushes. Local setup alone does not authorize publication. -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. Choose and create the independent starter @@ -25,68 +31,116 @@ Read the current [starter catalog](../starters/catalog.tsv) or run the installer The catalog currently offers `minimal` and `coreai`. Commands without `--starter` select Minimal for compatibility; agents should resolve the user's choice before creation. New catalog entries use the same commands. -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 --list bash install-starter.sh --starter coreai 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 --list bash scripts/create-prototype-repo.sh --starter coreai ../my-prototype ``` -Replace `coreai` with the chosen catalog ID. Both paths use the same creation implementation and assemble shared Replica tooling with only the selected app. They create an independent Git repository with all copied files in an initial commit on `main`, no remote and nothing published. This baseline provides the `HEAD` needed by worktrees and branch-based tools. The installer requires Bash, curl, tar and Git for download, or Bash and Git from a checkout. It does not require GitHub credentials, require or install Node.js for copying, or install app dependencies. +Replace `coreai` with the chosen catalog ID. Both paths use the same creation implementation and assemble shared Replica tooling with only the selected app: + +- They create an independent Git repository with all copied files in an initial commit on `main`, no remote, and nothing published. This gives worktrees and branch-based tools a starting commit. +- Downloaded installation requires Bash, curl, tar, and Git. Creation from a checkout requires Bash and Git. +- Copying requires no GitHub credentials or Node.js. The installer does not install Node.js or app dependencies. + +Git must have an author identity configured through `user.name` and `user.email` or its standard environment variables. The installer uses the existing Git configuration without changing it. + +**If creation fails:** The installer reports staging or commit errors and removes the incomplete destination. Resolve identity, signing, or hook failures before retrying. -Git must have an author identity configured through `user.name` and `user.email` or its standard environment variables. The installer uses the existing Git configuration without changing it. If staging or committing fails, it reports the Git error and removes the incomplete destination. Resolve identity, signing or hook failures before retrying. +Before the user accepts the new project's Copilot configuration, review `.github/github-app.yml` and the startup details in the copied `REPLICA.md`. Explain that session startup can install Copilot CLI globally if missing, install or enable the Replica plugin, and run `npm ci`. -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 `REPLICA.md`. Explain that session startup can install Copilot CLI globally when missing, install or enable the Replica plugin, and will run `npm ci`. +### Continue in a fresh session -Add the new directory to the Copilot app using **Sessions → + → Open folder**, then start a fresh session there. The session in the Replica checkout cannot discover the copied local skills. +Ask the user to open the repository folder in Copilot using **Sessions → + → Open folder**, then start a fresh session there. A session in the Replica checkout cannot discover the new repository's local skills. -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, chosen starter ID and name, supplied references, requested milestone, settled decisions and approvals, completed actions, blockers, and next step. +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: -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 user's goal and requested outcome. +- The project path, chosen starter ID and name, and supplied references. +- Decisions and approvals already given. +- Completed work, blockers, and the 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 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 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. -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. +1. Follow the copied `REPLICA.md` for canvas activation and preflight. Complete those checks before starting the preview. +2. Discover the selected app's run commands in its README and package scripts. Do not assume another starter's headings, router, or port. +3. Reuse a responsive server only after confirming it serves the intended app. Open the actual URL printed by the server. -Follow the copied `REPLICA.md` for canvas activation and preflight. Complete that preflight before starting a preview. Discover the selected app's run commands in its README and package scripts; do not assume another starter's headings, router or port. Reuse an existing responsive server only after confirming that it serves the intended app, 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. +For an adapted app without `REPLICA.md`, use the [shared canvas setup instructions](../starters/shared/REPLICA.md#connect-the-replica-canvas) alongside the app's own run commands. Preserve its existing instructions. -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. +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 | Preserve the app's supplied skills and active context. Run `/setup-skills` when guidance must be added or changed, reusing prior answers. Follow source intake, installation approval, draft review and separate activation steps. | -| Reference-based starting UI | Use supplied active guidance where it applies; offer setup only for missing task-required context. Use the local `create-prototype` skill and the selected app's conventions to build the requested shell or page. Establish the permitted component sources and 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 -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. +Preserve the app's supplied skills and active context. Run the project's `/setup-skills` when product or design-system guidance must be added or changed, using the supplied sources and 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. + +Report whether guidance is drafted, reviewed, or active. Drafting does not activate it. + +### Build from a reference + +Use supplied active guidance where it applies and complete setup only for missing task-required context. Then use the project's `create-prototype` skill and the selected app's conventions 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, commit any customizations after the installer's initial commit. Use the intended empty GitHub repository or create one with the agreed owner and visibility. Connect it as a remote named `origin` 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. +1. Review the starter files, active guidance, and starting pages. +2. With authorization, commit any customizations after the installer's initial commit. +3. Use the intended empty GitHub repository or create one with the agreed owner and visibility. +4. With authorization, connect it as `origin` and push the intended default branch. -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. +For an existing shared repository, follow its contribution process to merge the reviewed changes. Preserve its files, remote, and history. + +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 58034aa0..aef08a61 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 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. + +If a download is denied, resolve the network approval before retrying. These requirements do not authorize bypassing your organization's network controls. + ## Optional server-side tracing Hub can send server-side traces to an OpenTelemetry Protocol (OTLP) endpoint. Traces describe Rails requests, Active Job enqueueing and execution, instrumented Active Record operations, and outbound Net::HTTP calls. The published image includes OpenTelemetry instrumentation and its HTTP/protobuf exporter, not vendor-specific APM SDKs.