fix(doc): update instructions for first time setup

Author: krokoko

docs/guides/DEVELOPER_GUIDE.md

@@ -13,14 +13,18 @@ The repository is organized around four main pieces:
 
 ## Repository preparation
 
-The CDK stack ships with a **sample onboarded repository** (`krokoko/agent-plugins` in `src/stacks/agent.ts`) so the project deploys and tests cleanly out of the box. To use ABCA with **your** GitHub repositories, you need to point the platform at those repos and give the agent the right tools and permissions.
+The CDK stack ships with a **sample onboarded repository** (`krokoko/agent-plugins` in `src/stacks/agent.ts`) so the project deploys and CDK tests run cleanly out of the box. That value is for **default wiring only**: a real agent run **pushes branches and opens pull requests** with your GitHub PAT, so the onboarded repo must be one your token can **clone, push to, and open PRs on**. Most people do **not** have that access to the upstream repo.
+
+**Recommended first setup:** fork [`awslabs/agent-plugins`](https://github.com/awslabs/agent-plugins) on GitHub, set the `Blueprint` **`repo`** to **`your-github-username/agent-plugins`** (match your fork’s owner and repo name), and create a **fine-grained PAT** with access **only to that fork** (clone, push, PRs—see `agent/README.md` for scopes). Use that token for **`GITHUB_TOKEN`** when running `./agent/run.sh` locally and store the same value in Secrets Manager after deploy. For use on your own codebases, point the Blueprint at those repos instead and scope the PAT to match.
+
+Register every repo you want tasks to target and align tools and permissions (steps below).
 
 ### 1. Register repositories with `Blueprint` (required)
 
 The Task API only accepts tasks for repositories that are **onboarded** — each one is a `Blueprint` construct in `src/stacks/agent.ts` that writes a `RepoConfig` row to DynamoDB.
 
 1. Open **`src/stacks/agent.ts`** and locate the `Blueprint` block (for example `AgentPluginsBlueprint`).
-2. Set **`repo`** to your repository in **`owner/repo`** form (e.g. `acme/my-service`). This must match the `repo` field users pass in the CLI or API.
+2. Set **`repo`** to your repository in **`owner/repo`** form. For a quick end-to-end test, use your **fork** of the sample plugin repo (e.g. `jane-doe/agent-plugins` after forking `awslabs/agent-plugins`). For your own services, use something like `acme/my-service`. This must match the `repo` field users pass in the CLI or API.
 3. **Multiple repositories:** add another `new Blueprint(this, 'YourBlueprintId', { repo: 'owner/other-repo', repoTable: repoTable.table, ... })` and append it to the **`blueprints`** array. That array is used to aggregate per-repo **DNS egress** allowlists; skipping it can block the agent from reaching domains your Blueprint declares.
 
 Optional per-repo overrides (same file / `Blueprint` props) include a different AgentCore **`runtimeArn`**, **`modelId`**, **`maxTurns`**, **`systemPromptOverrides`**, or a **`githubTokenSecretArn`** for a dedicated PAT. If you use a custom `runtimeArn` or secret per repo, you must also pass the corresponding ARNs into **`TaskOrchestrator`** via **`additionalRuntimeArns`** and **`additionalSecretArns`** so the orchestrator Lambda’s IAM policy allows them (see [Repo onboarding](../design/REPO_ONBOARDING.md) for the full model).
@@ -29,7 +33,7 @@ After changing Blueprints, redeploy: `npx projen deploy`.
 
 ### 2. GitHub personal access token
 
-The agent clones, pushes, and opens pull requests using a **GitHub PAT** stored in Secrets Manager (see [Post-deployment setup](#post-deployment-setup)). The token must have permission to access **every** onboarded repository (clone, push to branches, create/update PRs). Use a fine-grained PAT scoped to the right org/repos; see `agent/README.md` for required scopes.
+The agent clones, pushes, and opens pull requests using a **GitHub PAT** stored in Secrets Manager (see [Post-deployment setup](#post-deployment-setup)). The token must have permission to access **every** onboarded repository (clone, push to branches, create/update PRs). Use a fine-grained PAT scoped to those repos—for the fork workflow above, restrict the token to **your fork** only; see `agent/README.md` for required scopes.
 
 ### 3. Agent image (`agent/Dockerfile`)
 
@@ -76,7 +80,7 @@ Default output format [None]: json
 - [Yarn](https://classic.yarnpkg.com/lang/en/docs/cli/install/) >= 1.22.19
 - [mise](https://mise.jdx.dev/getting-started.html) (required for local agent Python tasks and checks)
 - [Docker](https://docs.docker.com/engine/install/)
-- A **GitHub personal access token** (PAT) with permission to access every repository you onboard (clone, push to branches, create and update pull requests). After deployment, store it in the Secrets Manager secret the stack creates ([Post-deployment setup](#post-deployment-setup)); for local agent runs, export `GITHUB_TOKEN` (see **Local testing** below). Required scopes are documented in `agent/README.md`.
+- A **GitHub personal access token** (PAT) with permission to access every repository you onboard (clone, push to branches, create and update pull requests)—often a fine-grained token scoped to **your fork** of `awslabs/agent-plugins` if you follow the fork workflow under **Repository preparation** at the start of this guide. After deployment, store it in the Secrets Manager secret the stack creates ([Post-deployment setup](#post-deployment-setup)); for local agent runs, export `GITHUB_TOKEN` (see **Local testing** below). Required scopes are documented in `agent/README.md`.
 
 #### One-time AWS account setup
 
@@ -127,6 +131,8 @@ Before deploying to AWS, you can build and run the agent Docker container locall
 
 #### Prerequisites
 
+The `owner/repo` you pass to `run.sh` must match an onboarded Blueprint and be a repository your `GITHUB_TOKEN` can **push to and open PRs on** (same rules as **Repository preparation** at the start of this guide). If you have not changed the Blueprint, fork `awslabs/agent-plugins`, set **`repo`** to your fork, and use a PAT scoped to that fork—then pass the same **`owner/repo`** here.
+
 Set the following environment variables:
 
 ```bash