zuplo 7.8.7 → 7.8.8

package/docs/{articles/step-2-add-rate-limiting.mdx → getting-started/gateway/add-rate-limiting/index.mdx}

@@ -1,10 +1,19 @@
 ---
-title: Step 2 - Add Rate Limiting
-sidebar_label: "2 - Rate Limiting"
+category: API Management
+showLastModified: false
+suggestEdit: false
+title: Add rate limiting - Portal
+description:
+  Protect the gateway you just built by adding a rate limiting policy to a route
+  and watching it reject requests over the limit in the Zuplo Portal.
 ---
 
+<WizardSteps build="gateway" method="portal" step="add-rate-limiting" />
+
+<MethodTabs build="gateway" method="portal" step="add-rate-limiting" />
+
 In this guide we'll add simple Rate Limiting to a route. If you don't have one
-ready, complete [Step 1](./step-1-setup-basic-gateway.mdx) first.
+ready, complete [Step 1](../setup-a-basic-gateway/index.mdx) first.
 
 Rate Limiting is one of our most popular **policies** - you should never ship an
 API without rate limiting because your customers or internal developers **will**
@@ -12,10 +21,10 @@ accidentally DoS your API; usually with a rogue `useEffect` call in React code.
 
 :::info{title="What's a Policy?"}
 
-[Policies](./policies.mdx) are modules that can intercept and transform an
-incoming request or outgoing response. Zuplo offers a wide range of policies
-built-in (including rate limiting) to save you time. You can check out
-[the full list](../policies/overview.mdx).
+[Policies](../../../articles/policies.mdx) are modules that can intercept and
+transform an incoming request or outgoing response. Zuplo offers a wide range of
+policies built-in (including rate limiting) to save you time. You can check out
+[the full list](../../../policies/overview.mdx).
 
 :::
 
@@ -36,7 +45,7 @@ limiter.
 
    <ModalScreenshot>
 
-   ![Add policy](../../public/media/step-2-add-rate-limiting/image.png)
+   ![Add policy](../../../../public/media/step-2-add-rate-limiting/image.png)
 
    </ModalScreenshot>
 
@@ -44,7 +53,7 @@ limiter.
 
    <ModalScreenshot>
 
-   ![Add rate-limiting policy](../../public/media/step-2-add-rate-limiting/choose-rate-limiter.png)
+   ![Add rate-limiting policy](../../../../public/media/step-2-add-rate-limiting/choose-rate-limiter.png)
 
    </ModalScreenshot>
 
@@ -53,7 +62,7 @@ limiter.
    (`requestsAllowed`) every 1 minute (`timeWindowMinutes`). You can explore the
    rest of the policy's documentation and configuration in the right panel.
 
-   ![Rate limiting policy](../../public/media/step-2-add-rate-limiting/create-policy.png)
+   ![Rate limiting policy](../../../../public/media/step-2-add-rate-limiting/create-policy.png)
 
    To apply the policy, click **OK**. Then, save your changes to redeploy.
 
@@ -64,7 +73,7 @@ limiter.
 
    <ModalScreenshot>
 
-   ![429 response](../../public/media/step-2-add-rate-limiting/test-api.png)
+   ![429 response](../../../../public/media/step-2-add-rate-limiting/test-api.png)
 
    </ModalScreenshot>
 
@@ -72,6 +81,3 @@ limiter.
    echo API.
 
 </Stepper>
-
-**NEXT** Try
-[Step 3 - Add API Key Authentication](./step-3-add-api-key-auth.mdx).

package/docs/{articles/step-2-add-rate-limiting-local.mdx → getting-started/gateway/add-rate-limiting/local.mdx}

@@ -1,10 +1,20 @@
 ---
-title: Step 2 - Add Rate Limiting
-sidebar_label: "2 - Rate Limiting"
+category: API Management
+showLastModified: false
+suggestEdit: false
+title: Add rate limiting - Editor
+description:
+  Protect the gateway you just built by adding a rate limiting policy to a route
+  and watching it reject requests over the limit with the Zuplo CLI and your
+  editor.
 ---
 
+<WizardSteps build="gateway" method="local" step="add-rate-limiting" />
+
+<MethodTabs build="gateway" method="local" step="add-rate-limiting" />
+
 In this guide we'll add simple Rate Limiting to a route. If you don't have one
-ready, complete [Step 1](./step-1-setup-basic-gateway-local.mdx) first.
+ready, complete [Step 1](../setup-a-basic-gateway/local.mdx) first.
 
 Rate Limiting is one of our most popular **policies** - you should never ship an
 API without rate limiting because your customers or internal developers **will**
@@ -12,10 +22,10 @@ accidentally DoS your API; usually with a rogue `useEffect` call in React code.
 
 :::info{title="What's a Policy?"}
 
-[Policies](./policies.mdx) are modules that can intercept and transform an
-incoming request or outgoing response. Zuplo offers a wide range of policies
-built-in (including rate limiting) to save you time. You can check out
-[the full list](./policies.mdx).
+[Policies](../../../articles/policies.mdx) are modules that can intercept and
+transform an incoming request or outgoing response. Zuplo offers a wide range of
+policies built-in (including rate limiting) to save you time. You can check out
+[the full list](../../../articles/policies.mdx).
 
 :::
 
@@ -23,8 +33,8 @@ Zuplo offers a programmable approach to rate limiting that allows you to vary
 how rate limiting is applied for each customer or request.
 
 In this example, we'll add a simple IP-based rate limiter, but you should also
-explore [dynamic rate limiting](./step-5-dynamic-rate-limiting-local.mdx) to see
-the full power of the world's best rate limiter.
+explore [dynamic rate limiting](../dynamic-rate-limiting/local.mdx) to see the
+full power of the world's best rate limiter.
 
 <Stepper>
 
@@ -39,7 +49,7 @@ the full power of the world's best rate limiter.
 
    <BrowserScreenshot url="http://localhost:9100/?path=routes.oas.json">
 
-   ![Add Policy](../../public/media/step-2-add-rate-limiting-local/image.png)
+   ![Add Policy](../../../../public/media/step-2-add-rate-limiting-local/image.png)
 
    </BrowserScreenshot>
 
@@ -47,7 +57,7 @@ the full power of the world's best rate limiter.
 
    <ModalScreenshot>
 
-   ![Add rate-limiting policy](../../public/media/step-2-add-rate-limiting/choose-rate-limiter.png)
+   ![Add rate-limiting policy](../../../../public/media/step-2-add-rate-limiting/choose-rate-limiter.png)
 
    </ModalScreenshot>
 
@@ -56,7 +66,7 @@ the full power of the world's best rate limiter.
    (`requestsAllowed`) every 1 minute (`timeWindowMinutes`). You can explore the
    rest of the policy's documentation and configuration in the right panel.
 
-   ![Rate limiting policy](../../public/media/step-2-add-rate-limiting/create-policy.png)
+   ![Rate limiting policy](../../../../public/media/step-2-add-rate-limiting/create-policy.png)
 
    To apply the policy, click **Create Policy**, then save your changes.
 
@@ -90,6 +100,3 @@ the full power of the world's best rate limiter.
    your API.
 
 </Stepper>
-
-**NEXT** Try
-[Step 3 - Add API Key Authentication](./step-3-add-api-key-auth-local.mdx).

package/docs/getting-started/gateway/agent.mdx

@@ -0,0 +1,198 @@
+---
+category: API Management
+showLastModified: false
+suggestEdit: false
+title: Getting Started with API Gateway - Agent
+description:
+  Create a Zuplo API gateway project, configure its coding agent, then review
+  and deploy the agent's changes.
+---
+
+<WizardSteps build="gateway" method="agent" />
+
+<MethodTabs build="gateway" method="agent" />
+
+Put a managed gateway in front of any REST API. This path builds it with an AI
+coding agent.
+
+## Create your project
+
+:::note{title="Requirements"}
+
+[Node.js](https://nodejs.org/en/download) 24.0.0 or higher, a
+[Zuplo account](https://portal.zuplo.com), and an installed coding agent.
+
+:::
+
+<Stepper>
+
+1. **Create a local and hosted project**
+
+   Run:
+
+   ```bash
+   npx create-zuplo-api@latest example-project
+   cd example-project
+   ```
+
+   When prompted, choose **Yes** to create a matching Portal project, complete
+   sign-in, and select your Zuplo account. Select the coding agent you use when
+   asked. The CLI creates a project in the Portal and links your local
+   `example-project` directory to its working copy. The hosted project stores
+   the API key consumers and receives your deployment. If the CLI reports that
+   project creation failed, run
+   `npx zuplo project create --name example-project` from this directory. If
+   linking failed, or after creating the hosted project, run `npx zuplo link`
+   and select its working copy before continuing.
+
+   :::tip{title="Zuplo skills"}
+
+   The scaffold installs Zuplo skills in this project for Codex and Cursor and
+   configures the Claude Code plugin. If setup fails, follow
+   [Agent Skills](../../build-with-ai.mdx#agent-skills) from this directory
+   before starting your agent. The project's `.mcp.json` also configures the
+   Zuplo docs MCP server.
+
+   :::
+
+2. **Start the gateway**
+
+   ```bash
+   npm run dev
+   ```
+
+   Leave this running. The agent edits `config/` and `modules/`, and the dev
+   server hot-reloads.
+
+</Stepper>
+
+## Hand it to the agent
+
+One prompt covers the whole editor tutorial - forwarding, rate limiting, API key
+authentication, and dynamic limits. Paste it into Claude Code, Cursor, or Codex
+from inside your project directory.
+
+<Stepper>
+
+1. **Copy the prompt**
+
+   ```text
+   Read this project's agent instructions and the bundled docs in node_modules/zuplo/docs before writing code.
+
+   Build a Zuplo API gateway in this project:
+   1. Keep the default todo routes in config/routes.oas.json, but forward them to ${env.BASE_URL} and add BASE_URL=https://echo.zuplo.io to .env.zuplo.
+   2. Add the rate-limiting inbound policy (rateLimitBy: ip, 2 requests / 1 minute) to every route.
+   3. Add the api-key-inbound policy to every route, ordered before rate limiting.
+   4. Make rate limiting dynamic: create modules/rate-limit.ts exporting rateLimit() that returns 1000 req/min for user.data.customerType === "premium", 5 for "free", 30 otherwise, and switch the policy to rateLimitBy: "function".
+   5. Run npm run dev and verify with curl that GET /todos returns 401 without a key. I will create the free and premium keys in the Portal afterward; leave key-based tests for me.
+
+   Explain each config change in one line and stop before pushing to git.
+   ```
+
+1. **Review what it changed**
+
+   Expect edits to `config/routes.oas.json`, `config/policies.json`, a new
+   `modules/rate-limit.ts`, and `.env.zuplo`. Open the local
+   [Route Designer](../../articles/local-development-routes-designer.mdx) at
+   http://localhost:9100 to see the policies on each route.
+
+   :::tip
+
+   Ask the agent to explain any policy option you do not recognize. It has the
+   policy reference in `node_modules/zuplo/docs/policies/`.
+
+   :::
+
+</Stepper>
+
+## Create an API key and test
+
+The API key policy rejects everything until a consumer exists. Consumers live in
+the Zuplo Portal, not in code.
+
+<Stepper>
+
+1. **Create two consumers**
+
+   In the portal, open
+   [**Services**](https://portal.zuplo.com/+/account/project/services) › **API
+   Keys › Consumers › Create Consumer**. Create `free-consumer` with metadata
+   `{ "customerType": "free" }` and `premium-consumer` with
+   `{ "customerType": "premium" }`.
+
+   :::warning
+
+   Select the environment your local project is linked to with the **Dev /
+   Preview / Prod** switcher. With a single environment, pick **Prod**.
+
+   :::
+
+1. **Test both limits**
+
+   ```bash
+   # no key -> 401
+   curl -i http://localhost:9000/todos
+
+   # free key -> 429 on the 6th request within one minute
+   for i in 1 2 3 4 5 6; do
+     curl -i http://localhost:9000/todos \
+       --header 'Authorization: Bearer FREE_CONSUMER_KEY'
+   done
+
+   # premium key -> 1000 requests per minute
+   curl http://localhost:9000/todos \
+     --header 'Authorization: Bearer PREMIUM_CONSUMER_KEY'
+   ```
+
+   Replace `FREE_CONSUMER_KEY` and `PREMIUM_CONSUMER_KEY` with the keys from the
+   Portal. The premium request should succeed; its limit is 1000 requests per
+   minute, so a single request doesn't test the threshold.
+
+</Stepper>
+
+## Deploy
+
+Zuplo deploys from Git. The agent can do the push; the connection happens in the
+portal.
+
+<Stepper>
+
+1. **Ask the agent to push**
+
+   ```text
+   Commit everything, create an empty GitHub repo called example-project with gh, add it as origin and push main.
+   ```
+
+1. **Connect the repository in Zuplo**
+
+   ```bash
+   npx zuplo info
+   ```
+
+   Open the source-control link from the output, or **Settings › Source
+   Control** in the portal. Click **Connect to GitHub**, then **Connect** on
+   your repository. Zuplo deploys `main` immediately. Run `zuplo info` again to
+   confirm.
+
+   :::tip{title="Branch environments"}
+
+   Every branch you push gets its own isolated environment. See
+   [Branch-Based Deployments](../../articles/branch-based-deployments.mdx).
+
+   :::
+
+</Stepper>
+
+## Wrapping up
+
+You have built an API protected by API key authentication, dynamically rate
+limited, deployed to the edge, and documented in your developer portal - with an
+agent doing the configuration while you reviewed each change.
+
+### Next steps
+
+- Customize your [developer portal](../../dev-portal/overview.mdx) or explore
+  [integrations](https://zuplo.com/integrations)
+- [Grab time](https://zuplo.com/meeting) with the Zuplo team
+- Start generating revenue with the
+  [monetization tutorial](../../articles/monetization/index.mdx)

package/docs/{articles/step-4-deploying-to-the-edge.mdx → getting-started/gateway/deploy-to-the-edge/index.mdx}

@@ -1,24 +1,33 @@
 ---
-title: Step 4 - Deploying to the Edge
-sidebar_label: "4 - Deploy"
+category: API Management
+showLastModified: false
+suggestEdit: false
+title: Deploy to the edge - Portal
+description:
+  Connect your project to Git and deploy the gateway to more than 300 edge
+  locations, with an environment for every branch in the Zuplo Portal.
 ---
 
+<WizardSteps build="gateway" method="portal" step="deploy-to-the-edge" />
+
+<MethodTabs build="gateway" method="portal" step="deploy-to-the-edge" />
+
 In this guide we'll show you how to deploy your gateway to the edge, at over 300
 data-centers around the world. The act of deployment creates new
-[environments](./environments.mdx) and it's worth familiarizing yourself with
-[how environments work](./environments.mdx).
+[environments](../../../articles/environments.mdx) and it's worth familiarizing
+yourself with [how environments work](../../../articles/environments.mdx).
 
 In this tutorial we'll show the default workflow via GitHub, but note that we
 also support GitLab, BitBucket
 ([enterprise plan only](https://zuplo.com/pricing)) and
-[custom CI/CD](./custom-ci-cd.mdx).
+[custom CI/CD](../../../articles/custom-ci-cd.mdx).
 
 To follow this tutorial you'll need
 
 - a GitHub account (it's free, sign up at [github.com](https://github.com)).
-- a zuplo project - complete [Step 1](./step-1-setup-basic-gateway.mdx),
-  [Step 2](./step-2-add-rate-limiting.mdx) and
-  [Step 3](./step-3-add-api-key-auth.mdx) for a great start!
+- a zuplo project - complete [Step 1](../setup-a-basic-gateway/index.mdx),
+  [Step 2](../add-rate-limiting/index.mdx) and
+  [Step 3](../add-api-key-auth/index.mdx) for a great start!
 - to install the
   [Zuplo GitHub deployment](https://github.com/apps/zuplo/installations/new) to
   GitHub - you can
@@ -37,14 +46,14 @@ Let's get started:
    the auth flow. You'll need to grant permissions for any GitHub organizations
    you want to work with.
 
-   ![Connect GitHub](../../public/media/step-4-deploying-to-the-edge/image-1.png)
+   ![Connect GitHub](../../../../public/media/step-4-deploying-to-the-edge/image-1.png)
 
    Next, a dialog will open asking you to authorize Zuplo. Click the **Authorize
    Zuplo** button.
 
    <Framed size="sm">
 
-   ![Zuplo GitHub connection](../../public/media/step-4-deploying-to-the-edge/d6194a80-b6d6-429e-85a6-ae1cb4a3375e.png)
+   ![Zuplo GitHub connection](../../../../public/media/step-4-deploying-to-the-edge/d6194a80-b6d6-429e-85a6-ae1cb4a3375e.png)
 
    </Framed>
 
@@ -66,7 +75,7 @@ Let's get started:
 
    <Framed size="sm">
 
-   ![Installing Zuplo app](../../public/media/step-4-deploying-to-the-edge/eef76bd7-4d26-4f86-96e8-89ebede03beb.png)
+   ![Installing Zuplo app](../../../../public/media/step-4-deploying-to-the-edge/eef76bd7-4d26-4f86-96e8-89ebede03beb.png)
 
    </Framed>
 
@@ -76,7 +85,7 @@ Let's get started:
 
    <Framed size="sm">
 
-   ![Choosing repository to install](../../public/media/step-4-deploying-to-the-edge/ff482269-9aa2-44c3-8266-b2682b3d6ea5.png)
+   ![Choosing repository to install](../../../../public/media/step-4-deploying-to-the-edge/ff482269-9aa2-44c3-8266-b2682b3d6ea5.png)
 
    </Framed>
 
@@ -91,7 +100,7 @@ Let's get started:
    already a member of an account that has authorized Zuplo. To add Zuplo to a
    new organization click **Add GitHub Account** in the org picker list.
 
-   ![Connect Org](../../public/media/step-4-deploying-to-the-edge/image-2.png)
+   ![Connect Org](../../../../public/media/step-4-deploying-to-the-edge/image-2.png)
 
 1. Connect GitHub to your Project
 
@@ -101,7 +110,7 @@ Let's get started:
    repository** button. You will be prompted that this will open GitHub. Click
    to continue.
 
-   ![Create Repository](../../public/media/step-4-deploying-to-the-edge/image-3.png)
+   ![Create Repository](../../../../public/media/step-4-deploying-to-the-edge/image-3.png)
 
    In the GitHub UI, you can rename your repository if you want. Click the
    **Create repository** button at the bottom of the page and return to the
@@ -110,11 +119,11 @@ Let's get started:
    The portal will reload and you will see your new repository listed. Click
    **Connect** to connect Zuplo to that repository.
 
-   ![Connect](../../public/media/step-4-deploying-to-the-edge/image-4.png)
+   ![Connect](../../../../public/media/step-4-deploying-to-the-edge/image-4.png)
 
    After the connection succeeds you will see a link to your GitHub repository.
 
-   ![Connected Repository](../../public/media/step-4-deploying-to-the-edge/image-5.png)
+   ![Connected Repository](../../../../public/media/step-4-deploying-to-the-edge/image-5.png)
 
    Click the link to return to GitHub. You should see a little brown dot next to
    the commit hash (1). When you hover your mouse over that you'll see the Zuplo
@@ -123,12 +132,12 @@ Let's get started:
    This shows that your deployment is in progress, it will take about 50
    seconds.
 
-   ![Zuplo deployment run](../../public/media/step-4-deploying-to-the-edge/brown-dot.png)
+   ![Zuplo deployment run](../../../../public/media/step-4-deploying-to-the-edge/brown-dot.png)
 
    On the deployment page, you will see **Deployment has Completed!!** and below
    that's the link to your new environment.
 
-   ![Zuplo deployment run result](../../public/media/step-4-deploying-to-the-edge/26fa58b6-7a5a-4627-bd9f-246972639f12.png)
+   ![Zuplo deployment run result](../../../../public/media/step-4-deploying-to-the-edge/26fa58b6-7a5a-4627-bd9f-246972639f12.png)
 
 1. Deploy another Environment
 
@@ -138,7 +147,7 @@ Let's get started:
 
    Let's create a branch called `development`
 
-   ![Create new branch](../../public/media/step-4-deploying-to-the-edge/60cdeb36-ab7d-42f9-a8c2-1f7931f80ca6.png)
+   ![Create new branch](../../../../public/media/step-4-deploying-to-the-edge/60cdeb36-ab7d-42f9-a8c2-1f7931f80ca6.png)
 
    Wait about 20s and head back to Zuplo - you should see a new entry in the
    environment dropdown called `development`.
@@ -149,18 +158,18 @@ Let's get started:
    something simple like capitalize the **Summary** field from 'Get all todos'
    to 'Get All Todos'. It doesn't really matter what the change is.
 
-   ![Changes Summary](../../public/media/step-4-deploying-to-the-edge/image-6.png)
+   ![Changes Summary](../../../../public/media/step-4-deploying-to-the-edge/image-6.png)
 
    Save your changes. Click the GitHub button at bottom left and choose **Commit
    & Push**.
 
-   ![Commit & Push](../../public/media/step-4-deploying-to-the-edge/image-7.png)
+   ![Commit & Push](../../../../public/media/step-4-deploying-to-the-edge/image-7.png)
 
    Enter a description of your change in the dialog that pops up:
 
    <ModalScreenshot>
 
-   ![Change Summary](../../public/media/step-4-deploying-to-the-edge/image-8.png)
+   ![Change Summary](../../../../public/media/step-4-deploying-to-the-edge/image-8.png)
 
    </ModalScreenshot>
 
@@ -169,7 +178,7 @@ Let's get started:
 
    <ModalScreenshot>
 
-   ![Create PR](../../public/media/step-4-deploying-to-the-edge/image-9.png)
+   ![Create PR](../../../../public/media/step-4-deploying-to-the-edge/image-9.png)
 
    </ModalScreenshot>
 
@@ -177,21 +186,21 @@ Let's get started:
    Pull Request. Change the **base** branch to `development` (since that's the
    environment we want to update first). Click **Create pull request**.
 
-   ![GitHub PR](../../public/media/step-4-deploying-to-the-edge/875b164d-b7ef-4f46-9cdb-8d59354b5b93.png)
+   ![GitHub PR](../../../../public/media/step-4-deploying-to-the-edge/875b164d-b7ef-4f46-9cdb-8d59354b5b93.png)
 
    When ready, click **Merge pull request**.
 
-   ![Merge PR](../../public/media/step-4-deploying-to-the-edge/e8c68072-35dc-462a-8161-7a44e40fa1df.png)
+   ![Merge PR](../../../../public/media/step-4-deploying-to-the-edge/e8c68072-35dc-462a-8161-7a44e40fa1df.png)
 
    Once merged, you'll want to delete that temporary branch.
 
-   ![Delete branch](../../public/media/step-4-deploying-to-the-edge/51a25aa0-cdce-4112-ba2e-e56f42a9044d.png)
+   ![Delete branch](../../../../public/media/step-4-deploying-to-the-edge/51a25aa0-cdce-4112-ba2e-e56f42a9044d.png)
 
    The successful merge will trigger a rebuild and deployment of `development`
    with your change. You can check this by choosing the environment
    `development` in Zuplo and navigating to the **read only** Route Designer.
 
-   ![Navigating Environments](../../public/media/step-4-deploying-to-the-edge/image.png)
+   ![Navigating Environments](../../../../public/media/step-4-deploying-to-the-edge/image.png)
 
    This shows how you can use widely recognized GitOps practices to manage how
    code flows through your environments using Pull Requests and protected

package/docs/{articles/step-4-deploying-to-the-edge-local.mdx → getting-started/gateway/deploy-to-the-edge/local.mdx}

@@ -1,22 +1,51 @@
 ---
-title: Step 4 - Deploy to the Edge
-sidebar_label: "4 - Deploy"
+category: API Management
+showLastModified: false
+suggestEdit: false
+title: Deploy to the edge - Editor
+description:
+  Connect your project to Git and deploy the gateway to more than 300 edge
+  locations, with an environment for every branch with the Zuplo CLI and your
+  editor.
 ---
 
+<WizardSteps build="gateway" method="local" step="deploy-to-the-edge" />
+
+<MethodTabs build="gateway" method="local" step="deploy-to-the-edge" />
+
 In this guide we'll deploy your locally-developed gateway to the edge, at over
 300 data-centers around the world. Zuplo deploys from Git source control — once
 your project is connected to a GitHub repository, every push deploys
 automatically, with no CI/CD configuration required.
 
-The act of deployment creates new [environments](./environments.mdx), so it's
-worth familiarizing yourself with [how environments work](./environments.mdx).
+The act of deployment creates new
+[environments](../../../articles/environments.mdx), so it's worth familiarizing
+yourself with [how environments work](../../../articles/environments.mdx).
 
-To follow this tutorial you'll need a GitHub account (it's free, sign up at
-[github.com](https://github.com)).
+To follow this tutorial, you need a [GitHub account](https://github.com) and a
+Zuplo account. Your local project directory must also be linked to a hosted
+Zuplo project in the Portal. The local files alone cannot receive a deployment.
 
 <Stepper>
 
-1. **Check your project status**
+1. **Create and link a hosted project if needed**
+
+   If you answered **Yes** when `create-zuplo-api` asked to create a matching
+   Portal project, the CLI already created and linked its hosted project.
+   Otherwise, from your local project directory, create one and link its working
+   copy:
+
+   ```bash
+   npx zuplo project create --name example-project
+   npx zuplo link
+   ```
+
+   Sign in and select your Zuplo account when prompted. If you already created a
+   hosted project in the Portal, run only `npx zuplo link` and select that
+   project and its working copy. See
+   [Creating a matching portal project](../../../cli/create-zuplo-api.mdx#creating-a-matching-portal-project).
+
+2. **Check your project status**
 
    From your project directory, run `zuplo info` to see how your local project
    maps to Zuplo:
@@ -37,13 +66,13 @@ To follow this tutorial you'll need a GitHub account (it's free, sign up at
    connected to a repository yet. The next steps walk through connecting one so
    your changes deploy automatically.
 
-1. **Create a GitHub repository**
+3. **Create a GitHub repository**
 
    In GitHub, [create a new repository](https://github.com/new). Leave it
    **empty** — don't add a README, `.gitignore`, or license — since your project
    already contains those files.
 
-1. **Push your project to GitHub**
+4. **Push your project to GitHub**
 
    `create-zuplo-api` already initialized your project as a Git repository.
    Stage and commit your work (if you haven't already), then point your local
@@ -57,14 +86,15 @@ To follow this tutorial you'll need a GitHub account (it's free, sign up at
    git push -u origin main
    ```
 
-1. **Connect the repository in Zuplo**
+5. **Connect the repository in Zuplo**
 
    Open the source-control settings link from the `zuplo info` output, or in the
    Zuplo Portal open **Settings → Source Control**.
 
    If this is your first time, click **Connect to GitHub** and authorize the
-   Zuplo GitHub app — see [GitHub Setup](./source-control-setup-github.mdx) for
-   a detailed walkthrough of the authorization flow and permissions.
+   Zuplo GitHub app — see
+   [GitHub Setup](../../../articles/source-control-setup-github.mdx) for a
+   detailed walkthrough of the authorization flow and permissions.
 
    Once the app has access to your repositories, find the repository you just
    pushed to in the list and click **Connect**.
@@ -78,7 +108,7 @@ To follow this tutorial you'll need a GitHub account (it's free, sign up at
 
    :::
 
-1. **Verify your deployment**
+6. **Verify your deployment**
 
    As soon as the repository is connected, Zuplo deploys your `main` branch. In
    GitHub you'll see a status check next to your commit; when it succeeds, the
@@ -95,12 +125,10 @@ To follow this tutorial you'll need a GitHub account (it's free, sign up at
 
    Every branch you push gets its own isolated environment. Create a
    `development` branch, push it, and Zuplo deploys a matching environment
-   automatically. See [Branch-Based Deployments](./branch-based-deployments.mdx)
-   to learn how branches map to environments.
+   automatically. See
+   [Branch-Based Deployments](../../../articles/branch-based-deployments.mdx) to
+   learn how branches map to environments.
 
    :::
 
 </Stepper>
-
-**NEXT** Try
-[Step 5 - Add Dynamic Rate Limiting](./step-5-dynamic-rate-limiting-local.mdx).