atlassian
diff --git a/‎skills/forge-onboarding/README.md‎
Lines changed: 12 additions & 8 deletions b/‎skills/forge-onboarding/README.md‎
Lines changed: 12 additions & 8 deletions
@@ -1,6 +1,11 @@
 # Forge Onboarding Skill
 
-The **first guided experience for someone new to Atlassian Forge**, optimized for AI-native development. Takes a first-time builder from zero to a running Rovo Agent — **Forge Guru**, a permanent Forge development companion that lives on their dev site and answers Forge questions live from the official developer docs.
+**Forge lets you build apps that extend Atlassian products, connect platform data, and power AI experiences.** This skill teaches the core building blocks of a Forge app by walking a first-time developer through building a **Rovo Agent** from scratch.
+
+By the end of ~15 minutes, the learner understands three things:
+1. **The foundation** — the pieces every Forge app is made of (manifest, modules, functions, permissions, deploy, install, logs).
+2. **How Forge connects into the wider Atlassian platform** — Rovo, Actions, Teamwork Graph, product APIs, the full surface Forge apps can reach.
+3. **How those pieces come together in a real app** — because they'll have built one: **Forge Guru**, a permanent Forge companion that lives on their dev site and answers Forge questions live from the official developer docs.
 
 Use this skill for your **first** Forge app. For everything after that, use `forge-app-builder`.
 
@@ -33,7 +38,7 @@ Users see section titles (e.g. *"Deploy your first Forge app"*, *"See Hello Worl
 
 0. **Welcome & frame** — Introduce Forge Guru by name in the very first line, sketch the two-loop shape of the onboarding (Set up → Loop 1 → Loop 2 → What next), and set the expectation that today's artifact is a keep-forever tool.
 1. **Set up your local machine** — Verify (and install, with permission) Node.js, the Forge CLI, and `forge login`. This is the *local* half of setup — the tools on your machine. The *Atlassian* half comes later in Step 4.
-2. **The AI-native Forge app mental model** — The four concepts of every Forge app, presented as a scannable table: **manifest**, **modules & extension points**, **the Context Moat (Teamwork Graph + MCP)**, and **backend (actions & resolvers)**. Includes a 6-step "what actually happens when you chat with a Rovo Agent" walkthrough.
+2. **What Forge is, and what we're building today** — Split into two visible sub-beats. **Step 2a** paints Forge broadly (foundation building blocks + the wider Atlassian platform: product surfaces, Rovo, Teamwork Graph in EAP, product APIs, external APIs) so users don't leave thinking Forge = Rovo Agent framework. **Step 2b** narrows deliberately: *"of everything Forge can do, we're building one Rovo Agent today because it's the fastest way to feel Forge's full pipeline end-to-end — and everything transfers."* Presents the **three building blocks** the user will actually touch (manifest, module, backend function) as a scannable table. The runtime walkthrough (*"what actually happens when you type a message to a Rovo Agent"*) is deliberately deferred to Step 8, where the user has just chatted with their agent and the concepts land against something concrete.
 3. **Meet Forge Guru** — Purely conceptual: introduce the specific agent we're building (what it is, what you'll be able to ask it, what it's built from, why it's worth keeping). No user inputs collected here.
 4. **Set up your Atlassian environment** — A super-step with three symmetric micro-beats, each in its own visible section so no beat disappears into narration. This is the *Atlassian* half of setup — where the app will live, who will own it, and where it'll run. The *local* half was handled in Step 1.
    - **4a — Choose where your Forge agent will live** (working directory on disk).
@@ -44,13 +49,13 @@ Users see section titles (e.g. *"Deploy your first Forge app"*, *"See Hello Worl
 
 5. **Scaffold your Rovo Agent** — Delegate to the **`forge-app-builder`** skill's non-interactive helper (`scripts.create_forge_app --template rovo-agent-rovo --name forge-guru`) to scaffold a stock Hello World Rovo Agent from the official template. A short teaching beat at the end of this step reinforces how `forge create` names things: the `--name` flag locks three names to the same value at once — the folder on disk (`forge-guru/`), the app's immutable ID in the Developer Console (`forge-guru`), and the Rovo Agent's display name (`Forge Guru`). The name doesn't change again — Loop 2 only customizes what Guru *does*, not what it's called.
 6. **Take a look at what the scaffold gave us** — Two messages, one per file. Chat carries a compact concept summary (what the file is for, what blocks it contains, how the pieces connect, cross-referenced to Step-3 concepts). Each message ends with the exact path to the file on disk so a curious user can open it in their editor to see the syntax. **No files are modified in this step** — the on-disk scaffold stays exactly as `forge create` produced it until Step 9.
-7. **Deploy your first Forge app** — Delegate to `scripts.deploy_forge_app`, which runs `forge deploy` + `forge install` in one non-interactive call (with `npm install` handled automatically as part of deploy). Explicit user confirmation required. First Forge deploy of the user's career — celebrate it.
-8. **See Hello World live on your dev site** — Click-by-click instructions for opening Rovo, finding the agent, and chatting with it. First confidence beat — the user sees their own code respond in Rovo.
+7. **Deploy your first Forge app** — Two plain CLI commands invoked directly: `forge deploy --non-interactive` followed by `forge install --non-interactive --site <site-url> --product jira -e development`. `npm install` is handled automatically by `forge deploy`. Explicit user confirmation required. First Forge deploy of the user's career — celebrate it.
+8. **See Hello World live on your dev site** — Click-by-click instructions for opening Rovo, finding the agent, and chatting with it. First confidence beat — the user sees their own code respond in Rovo. Once they confirm the agent responded, the skill walks through **what just happened server-side** (message → manifest → module → action → function → response) — the runtime walkthrough deliberately deferred from Step 2 so it lands against something concrete.
 
 **Loop 2 — turn the same app into Forge Guru:**
 
-9. **Turn Hello World into Forge Guru** — Two per-file confirm-gates, one for `manifest.yml` and one for `src/index.js`. Chat carries a compact **change list** (what's changing and why, cross-referenced to Step-3 concepts) — not a full target-file paste. Escape hatch: if the user says *"show me the file"* the agent pastes the full target YAML/JS from the pinned reference. On confirm, files are overwritten with **clean, production-shaped Guru code** (short 2-line header + code) so the app now looks like a real Forge app. **The `src/index.js` gate also updates `package.json`** as an inline side-effect — the new Guru handler imports `@forge/api`, which the stock scaffold may not declare as a dependency, so the agent adds it and tells the user in the same message. All pinned target-file YAML in the skill is hard-wrapped so every source line is ≤160 characters — this keeps the redeploy in Step 10 from failing `forge lint`.
-10. **Redeploy — this time as Forge Guru** — Same `scripts.deploy_forge_app` helper, second time. `forge deploy` picks up the new `@forge/api` dependency automatically as part of its install-and-deploy pipeline. The daily-rhythm beat — the user sees that iterating on a Forge app is just *edit → redeploy → see it live*.
+9. **Turn Hello World into Forge Guru** — Two per-file confirm-gates, one for `manifest.yml` and one for `src/index.js`. Chat carries a compact **change list** (what's changing and why, cross-referenced to Step-3 concepts) — not a full target-file paste. Escape hatch: if the user says *"show me the file"* the agent pastes the full target YAML/JS from the pinned reference. On confirm, files are overwritten with **clean, production-shaped Guru code** (short 2-line header + code) so the app now looks like a real Forge app. **The `src/index.js` gate does three things atomically:** rewrites `src/index.js`, adds `@forge/api` to `package.json`, and runs `npm install` to sync `node_modules/` — so Step 10's redeploy doesn't fail with `Cannot find module '@forge/api'`. A one-sentence teaching moment reinforces the *package.json declares → npm install syncs → node_modules holds* mental model. All pinned target-file YAML in the skill is hard-wrapped so every source line is ≤160 characters — this keeps the redeploy in Step 10 from failing `forge lint`.
+10. **Redeploy — this time as Forge Guru** — Same two plain CLI commands as Step 7, with `--upgrade --confirm-scopes` added to `forge install` to acknowledge the new external-fetch scope Guru introduces. `forge deploy` picks up the new `@forge/api` dependency automatically. The daily-rhythm beat — the user sees that iterating on a Forge app is just *edit → redeploy → see it live*.
 11. **See Forge Guru live** — Same shape as Step 8, but this time the user asks Guru a real Forge question and gets back an answer with a cited doc link.
 12. **What next — the rest of your Forge journey** — Framed around Atlassian's official [*Build and launch your Forge app*](https://developer.atlassian.com/platform/forge/build-and-launch-your-forge-app/) doc: the user just finished the guided *Build* stage; here's the map for *Prepare to publish*, *Distribute*, and *Grow*. Includes a *"Get inspired"* section that points at three open-source Forge apps on [atlassian-labs/forge-inspired](https://github.com/atlassian-labs/forge-inspired) (Sprint Ready Agent, Smart Workflow Follow-up, Team Pulse Board), plus specialist skills routed to the stage where they help (`forge-security-review` / `forge-app-review` / `forge-cost-optimizer` under *Prepare to publish*; `forge-app-builder` / `forge-connector` / `forge-debugger` for continuing to build). Guru is the "one Rovo chat away" CTA.
 
@@ -85,7 +90,6 @@ This onboarding skill is a **thin, guided wrapper** around the `forge-app-builde
 | `forge-app-builder` helper | Used in | What it does |
 |---|---|---|
 | `scripts.create_forge_app` | Step 5 (Scaffold your Rovo Agent) | Non-interactive `forge create` — registers a new app, drops the starter project, bypasses the interactive template picker |
-| `scripts.deploy_forge_app` | Step 7 (Deploy Hello World) and Step 10 (Redeploy as Forge Guru) | Non-interactive `forge deploy` + `forge install` in one call — invoked twice, once per loop of the arc |
 | `scripts.list_templates` | Step 5 (fallback path) | Validates the Rovo Agent template name if the CLI ever renames it |
 
 The onboarding skill only invokes read-only Forge CLI commands directly — `forge --version`, `forge whoami`, `forge site provision`, `forge developer-spaces list`, `forge install list`, `forge logs`. Everything else routes through the helpers above.
@@ -118,7 +122,7 @@ This skill is only for **first-time** Forge users. Once you have Guru running, r
 
 ## Scripts
 
-This skill has no scripts of its own — it's purely instructional so the user sees each command as it runs and understands the mechanics. Every step that mutates Forge state delegates to a `forge-app-builder` helper: `scripts.create_forge_app` for the scaffold (Step 5), and `scripts.deploy_forge_app` for deploy + install — invoked twice, once for the stock Hello World in Step 7 and again for Forge Guru in Step 10. See the [Sibling skill dependency](#sibling-skill-dependency) section above.
+This skill has no scripts of its own — it's purely instructional so the user sees each command as it runs and understands the mechanics. The one delegation is `scripts.create_forge_app` (from `forge-app-builder`) for the scaffold step, because `forge create` is interactive and hand-rolling it goes wrong in subtle ways. `forge deploy` and `forge install` are invoked directly with plain flags — see Steps 7 and 10 for the exact commands.
 
 ## See Also