create-powerapp 1.0.0

package/docs/setup-guide.md

@@ -0,0 +1,968 @@
+# VS Code Setup Guide for Vibe Coding
+### Using GitHub Copilot or Claude Code
+
+> **Who is this for?** Anyone who wants to build Power Apps using AI — even if you have never written a line of code, never heard of VS Code, and have no idea what "the terminal" is. Follow this guide from top to bottom. Every unfamiliar word is explained. Take it one step at a time.
+
+---
+
+## ⚡ The Fast Way — One Command to Start Any Project
+
+> **Already completed the VS Code setup below?** This is all you need to start a new project. Run one command, answer four questions, and your entire project is scaffolded and open in VS Code — ready for you to start prompting your AI.
+
+```bash
+npx create-powerapp
+```
+
+That's it. The tool will ask you:
+
+1. **What do you want to call your project?** (e.g. `employee-leave-app`)
+2. **Which type of Power App?** (Canvas / Model-Driven / PCF / Power Pages / Code App)
+3. **Which AI assistant?** (GitHub Copilot or Claude Code)
+4. **Your Power Platform environment URL** (optional — you can add it later)
+
+Then it automatically creates:
+
+- ✅ Your project folder with the right structure for that app type
+- ✅ `.gitignore` — so passwords and auto-generated files never get uploaded
+- ✅ `.env` — a safe place to store your environment URL and secrets
+- ✅ `README.md` — project overview with useful commands
+- ✅ `instructions/` folder — AI context files that teach your AI how this app type works
+- ✅ `prompts/starter.md` — ready-made prompts you can copy and paste to get your first screens built immediately
+- ✅ `CLAUDE.md` or `.github/copilot-instructions.md` — the file your AI reads to understand your project
+- ✅ Git initialised with a first commit
+- ✅ Power Platform environment connected (if you provided the URL)
+- ✅ VS Code opened automatically
+
+**After the command finishes:**
+1. VS Code opens with your project
+2. Open `prompts/starter.md` — it has ready-made first prompts tailored to your app type
+3. Open your AI assistant (Copilot Chat icon, or run `claude` in the terminal)
+4. Copy a prompt from `prompts/starter.md`, paste it in, and start building
+
+---
+
+### Installing `create-powerapp` (one-time)
+
+You need Node.js installed first (covered in Part 1, Step 2 below). Then you can either run it directly with `npx` (no install needed) or install it globally so it's always available:
+
+```bash
+# Option 1 — run without installing (always uses the latest version)
+npx create-powerapp
+
+# Option 2 — install globally so you can run it anytime
+npm install -g create-powerapp
+create-powerapp
+```
+
+---
+
+## 🗺️ Before You Start — Read This First
+
+### What will I be doing?
+
+By the end of this guide, you will have a laptop set up so you can **describe an app in plain English** and have an AI build it for you. You will not need to memorise code. You will not need a computer science degree. You just need to be able to type sentences.
+
+### What is "Vibe Coding"?
+
+Vibe coding means you describe what you want to build in plain English, and an AI assistant (GitHub Copilot or Claude Code) writes the code for you. You guide, review, and refine — the AI does the heavy lifting. Think of it as pair programming with a very fast AI colleague.
+
+**Real example:** Instead of writing hundreds of lines of code yourself, you type something like:
+
+> *"Create a form that lets employees submit time-off requests. It should have a date picker, a dropdown for the reason, and a submit button that saves to a SharePoint list."*
+
+…and the AI writes all the code for you. Your job is to review it, test it, and ask for changes in plain English.
+
+### What is VS Code?
+
+VS Code (Visual Studio Code) is a free text editor made by Microsoft. Think of it like Microsoft Word, but instead of writing documents, you write instructions for computers (code). It also has a built-in terminal (a text-based command line) and can connect to AI assistants. You do not need to know how to code to use it — the AI inside it does that for you.
+
+### What are Power Apps?
+
+Power Apps is Microsoft's platform for building business apps — things like employee portals, approval workflows, data entry forms, customer-facing websites, and more. There are several types of Power Apps:
+
+| App Type | Think of it as… |
+|---|---|
+| **Canvas App** | A blank canvas — you design every screen, like building a PowerPoint slide that works as an app |
+| **Model-Driven App** | A database-first app — great for CRM-style tools where the data structure drives the layout |
+| **Code Component (PCF)** | A custom control you embed inside another app — like a special interactive widget |
+| **Power Pages** | A public-facing website connected to your business data |
+| **Code App** | A modern web app (like a React website) that runs inside Power Platform |
+
+You do not need to choose right now. This guide sets up your machine for all of them.
+
+### How long will this take?
+
+About **60–90 minutes** the first time, mostly waiting for software to download. Once set up, starting a new project takes about 5 minutes.
+
+### What do I need?
+
+- A Windows, macOS, or Linux computer
+- An internet connection
+- A Microsoft 365 / work account (for connecting to Power Apps)
+- Either a GitHub Copilot subscription or an Anthropic API key (your organisation may provide one — ask your IT team or manager)
+
+---
+
+## 🧩 Jargon Glossary
+
+You will see these words throughout the guide. Here is what they mean in plain English:
+
+| Word | Plain English meaning |
+|---|---|
+| **Terminal** | A text-based window where you type commands. Like a chat with your computer. |
+| **Command** | A short instruction you type into the terminal and press Enter to run. |
+| **Install** | Download and set up a program so it runs on your computer. |
+| **npm** | A tool that downloads and manages coding libraries automatically. Comes with Node.js. |
+| **Node.js** | A behind-the-scenes engine that runs JavaScript on your computer. Most tools need it. |
+| **Git** | A save-and-history system for code. Like "Track Changes" in Word, but for entire projects. |
+| **Repository / Repo** | A project folder tracked by Git. |
+| **CLI** | Command Line Interface — a tool you use by typing commands instead of clicking buttons. |
+| **Extension** | An add-on for VS Code, like a plugin. Gives VS Code new abilities. |
+| **Environment** | A Power Platform workspace — like a separate sandbox where your apps live. |
+| **Solution** | A bundle/container in Power Apps that holds your apps, data tables, and settings together. |
+| **PAC CLI** | Microsoft's command-line tool for Power Apps — lets you manage apps from the terminal. |
+| **YAML / XML** | Types of structured text files that store settings. The AI handles these — you rarely edit them directly. |
+| **Push / Pull** | Uploading your local changes to the server (push), or downloading the server's latest version (pull). |
+| **Package.json** | A file that lists what libraries a project needs. Like a recipe ingredient list. |
+
+---
+
+## Part 1 — Local Device Setup
+
+These steps are done **once on your machine**. You only need to do this again if you get a new computer.
+
+---
+
+### Step 1: Install VS Code
+
+**What is this?** VS Code is the app where you will do all your work. Think of it as your coding workbench.
+
+1. Go to [https://code.visualstudio.com](https://code.visualstudio.com)
+2. Click **Download** — it will auto-detect your operating system (Windows / macOS / Linux)
+3. Run the installer and follow the on-screen steps — click Next/Continue/Agree through all the defaults
+4. Open VS Code once the install finishes
+
+**What you should see:** A dark-themed window with a welcome tab, a sidebar on the left with icons, and a menu bar at the top. That is VS Code.
+
+> **macOS tip:** After installing, drag VS Code into your Applications folder so you can find it easily.
+
+---
+
+### Step 2: Install Node.js (Required for most projects)
+
+**What is this?** Node.js is a behind-the-scenes engine that almost every modern coding tool depends on. You won't use it directly — it just needs to be there. Installing it also gives you **npm**, which is a tool for downloading other tools automatically.
+
+1. Go to [https://nodejs.org](https://nodejs.org)
+2. Download the **LTS** version (the one labeled "Recommended for most users")
+3. Run the installer with all default settings — just keep clicking Next
+
+**Now check it worked.** You need to open the terminal inside VS Code:
+
+> **How to open the terminal in VS Code:** Press `` Ctrl+` `` (Windows/Linux) or `` Cmd+` `` (macOS). Alternatively, go to the top menu: **View → Terminal**. A panel will appear at the bottom of VS Code. That dark text area is your terminal.
+
+Type these two commands one at a time, pressing **Enter** after each:
+
+```
+node --version
+npm --version
+```
+
+Both commands should print a version number (e.g. `v20.11.0`). If they do, Node.js is installed correctly.
+
+> **If you see "command not found":** Close VS Code completely, re-open it, and try again. If still broken, re-run the Node.js installer.
+
+---
+
+### Step 3: Install Git
+
+**What is this?** Git is a save-and-history system for your code. Every time you finish a chunk of work, you "commit" it — this saves a snapshot you can go back to later. It also lets you share code with teammates. Think of it like "Track Changes" in Word, but for entire projects.
+
+- **Windows:** Download from [https://git-scm.com](https://git-scm.com) and run the installer (keep all defaults — just click Next through everything)
+- **macOS:** Run `git --version` in the terminal — macOS will automatically prompt you to install it. Click Install in the pop-up.
+- **Linux:** Run `sudo apt install git` in your terminal and type Y when asked
+
+**After installing, tell Git your name and email** (it stamps these on every save you make). In the terminal, run these two lines one at a time — replace the example values with your own:
+
+```
+git config --global user.name "Your Name"
+git config --global user.email "you@example.com"
+```
+
+No output means it worked — that's normal for Git.
+
+---
+
+### Step 4: Install Power Platform CLI (PAC CLI)
+
+**What is this?** The PAC CLI (Power Platform Command Line Interface) is Microsoft's official tool for connecting your VS Code to Power Apps. It lets you download apps to edit locally, push your changes back to the cloud, and manage your Power Apps environment — all from the terminal. Think of it as the bridge between your laptop and Power Apps.
+
+It lets you pull, push, and manage Power Apps components (Model-Driven Apps, Canvas Apps, Code Components, Code Apps, Power Pages) directly from VS Code and your terminal — no browser needed for most tasks.
+
+---
+
+#### 4a — Install the PAC CLI
+
+In the VS Code terminal, run one of these (Option 1 is recommended):
+
+**Option 1 — Via npm (recommended, works on all OS):**
+```
+npm install -g pac
+```
+
+**Option 2 — Via .NET tool** (if Option 1 fails):
+```
+dotnet tool install --global Microsoft.PowerApps.CLI.Tool
+```
+
+> The `-g` flag means "install globally" — so it works from any folder, not just one project.
+
+**Check it installed:**
+```
+pac --version
+```
+You should see something like `Microsoft PowerApps CLI 1.x.x`. If you do, it worked.
+
+---
+
+#### 4b — Install the Power Platform VS Code Extension
+
+**What is this?** Extensions add new abilities to VS Code. This one adds a Power Platform sidebar panel so you can manage your apps without leaving VS Code.
+
+1. In VS Code, click the **Extensions icon** in the left sidebar (it looks like four squares, with one slightly separated)
+   — or press `Ctrl+Shift+X` (Windows/Linux) / `Cmd+Shift+X` (macOS)
+2. In the search box at the top of the Extensions panel, type: **Power Platform Tools**
+3. Find the result published by **Microsoft** and click **Install**
+
+| Extension | Publisher | Purpose |
+|---|---|---|
+| **Power Platform Tools** | Microsoft | Full PAC CLI integration inside VS Code — manage environments, solutions, and apps from the sidebar |
+
+**What you should see after installing:** A new icon that looks like a Power Platform logo appears in the VS Code left sidebar. Clicking it shows your Power Apps environments.
+
+---
+
+#### 4c — Authenticate PAC CLI with Your Environment
+
+**What is this?** Before PAC CLI can talk to your organisation's Power Apps, you need to log in. This step connects the CLI to your Microsoft work account. You only do this once per environment.
+
+**What is a Power Platform environment?** Think of it as a workspace — your organisation might have a "Development" environment for testing and a "Production" environment for the live apps. Ask your manager or IT team which URL to use.
+
+Run this in the terminal (replace the URL with your organisation's):
+
+```
+pac auth create --url https://yourorg.crm.dynamics.com
+```
+
+> **How do I find my organisation's URL?** Log in to [make.powerapps.com](https://make.powerapps.com), click the settings gear → **Session details**, and look for "Instance url". It looks like `https://yourcompany.crm.dynamics.com`.
+
+A browser window will open asking you to sign in with your Microsoft 365 / work account. Sign in as normal. After sign-in, the CLI stores your credentials locally — you won't need to do this again.
+
+**Useful commands for managing your login:**
+
+```
+pac auth list           # See all the environments you're logged into
+pac auth select --index 1    # Switch to a different environment (use the number from pac auth list)
+```
+
+---
+
+#### 4d — Power Apps Component Skill Files
+
+**What is this?** Each type of Power App has its own code structure and conventions. This section sets up instruction files that teach your AI assistant how each app type works — so it gives you accurate, relevant suggestions instead of generic ones. Think of these as a briefing document you hand to a new colleague before they start work.
+
+Set these up **once locally** so your AI assistant understands Power Platform patterns.
+
+---
+
+##### Model-Driven Apps (MDA)
+
+**What is a Model-Driven App?** This is a database-first app — the structure of your data (tables, columns, relationships) drives how the app looks. Great for CRM tools, service management systems, or anything where you're managing lots of structured records. Power Apps generates most of the UI automatically from your data model.
+
+**In plain English:** You define the data, Power Apps builds the screens. Less design work, more data work.
+
+Use PAC CLI to work with them:
+
+```bash
+# Pull a solution containing MDA components
+pac solution clone --name YourSolutionName --outputDirectory ./solutions/your-solution
+
+# Typical local folder structure after clone:
+solutions/
+  your-solution/
+    src/
+      Entities/          # Dataverse table definitions
+      Forms/             # Form XML layouts
+      Views/             # View definitions
+      SiteMaps/          # App navigation
+    solution.xml
+```
+
+**AI instructions file** — create a file called `instructions/mda-instructions.md` in your project folder and paste this inside it. This tells the AI how Model-Driven Apps work so it can help you correctly:
+
+```markdown
+# Model-Driven App Instructions
+
+## Type: Model-Driven App (Power Apps / Dataverse)
+- All entities map to Dataverse tables
+- Forms are defined in XML — do not hand-edit GUIDs
+- Business rules go in Dataverse, not client-side JS
+- Use PAC CLI to push/pull: `pac solution push` / `pac solution clone`
+- Plugin code goes in the Plugins/ folder, registered via Plugin Registration Tool
+- JavaScript web resources live in WebResources/ and must be registered on forms
+```
+
+---
+
+##### Canvas Apps
+
+**What is a Canvas App?** This is a drag-and-drop app where you control every pixel of the design. Great for custom-branded employee tools, mobile apps, kiosks, and anything where the visual design matters. You build screens like PowerPoint slides, then connect them to data.
+
+**In plain English:** You design exactly how it looks and behaves. More creative control, more work.
+
+PAC CLI unpacks them into editable YAML files you can edit locally:
+
+```bash
+# Unpack a Canvas App from a solution for editing
+pac canvas unpack --msapp ./CanvasApp.msapp --sources ./canvas-src
+
+# Pack it back before pushing
+pac canvas pack --msapp ./CanvasApp.msapp --sources ./canvas-src
+
+# Typical unpacked folder structure:
+canvas-src/
+  Src/
+    App.fx.yaml          # App-level formulas and settings
+    Screens/             # One .fx.yaml file per screen
+  Assets/                # Images, icons, fonts
+  DataSources/           # Connected data source definitions
+  pkgs/                  # Component libraries
+```
+
+**AI instructions file** — create `instructions/canvas-instructions.md`:
+
+```markdown
+# Canvas App Instructions
+
+## Type: Canvas App (Power Apps)
+- Screens and controls are defined in .fx.yaml files
+- Formulas use Power Fx — similar to Excel syntax
+- Use `With()`, `Collect()`, `Patch()` for data operations — never SQL
+- Navigation: `Navigate(ScreenName, ScreenTransition.Fade)`
+- Avoid nested galleries where possible — use collections instead
+- PAC commands: `pac canvas unpack` / `pac canvas pack`
+- Never edit .msapp binary directly — always unpack first
+```
+
+---
+
+##### Code Components (PCF — Power Apps Component Framework)
+
+**What is a Code Component?** A PCF component is a custom interactive control you build once and then embed inside Canvas or Model-Driven Apps. Think of it as a reusable widget — for example, a custom colour picker, a signature pad, an interactive chart, or a drag-and-drop list. Built with standard web technologies (React and TypeScript), they look and behave exactly how you design them.
+
+**In plain English:** You're building a reusable UI lego brick that snaps into your other Power Apps.
+
+```bash
+# Create a new PCF project
+pac pcf init --namespace YourNamespace --name YourComponentName --template field
+
+# Install dependencies
+npm install
+
+# Run in local test harness (opens a preview in your browser)
+npm start watch
+
+# Build for deployment
+npm run build
+
+# Push to environment
+pac pcf push --publisher-prefix yourprefix
+
+# Typical folder structure:
+YourComponentName/
+  YourComponentName/
+    index.ts             # Main component logic
+    ControlManifest.xml  # Component metadata and properties
+  __tests__/             # Unit tests
+  node_modules/
+  package.json
+```
+
+**AI instructions file** — create `instructions/pcf-instructions.md`:
+
+```markdown
+# PCF Code Component Instructions
+
+## Type: Power Apps Component Framework (PCF)
+- Entry point is always `index.ts` implementing `ComponentFramework.StandardControl`
+- Properties are declared in `ControlManifest.Input.xml`
+- Use `context.parameters` to read input properties
+- Use `notifyOutputChanged()` to push values back to the app
+- Styling: use CSS modules or inline styles — no Tailwind
+- Testing: use `@testing-library/react` + Jest
+- Build: `npm run build` then `pac pcf push`
+- Never modify `.pcfproj` or `Solution.xml` by hand
+```
+
+---
+
+##### Power Pages (Portals)
+
+**What is Power Pages?** Power Pages are external-facing websites connected to your Dataverse data. Great for customer portals, partner sites, self-service forms, or any situation where people outside your organisation need to interact with your business data — without needing a Microsoft account.
+
+**In plain English:** A public website that your customers or partners can visit, powered by your Power Apps data behind the scenes.
+
+```bash
+# Download a Power Pages site to edit locally
+pac pages download --path ./powerpages-site --webSiteId your-website-id
+
+# Upload changes back
+pac pages upload --path ./powerpages-site
+
+# Typical folder structure:
+powerpages-site/
+  web-files/             # CSS, JS, image assets
+  web-pages/             # Page content in HTML/Liquid
+  web-templates/         # Reusable Liquid templates
+  content-snippets/      # Reusable text blocks
+  entity-forms/          # Dataverse-connected forms
+  web-roles/             # Access control roles
+```
+
+**AI instructions file** — create `instructions/powerpages-instructions.md`:
+
+```markdown
+# Power Pages Instructions
+
+## Type: Power Pages (External Portal)
+- Pages use Liquid templating language — similar to Jinja2
+- Data access uses FetchXML or Liquid tags like `{% fetchxml %}`
+- CSS and JS go in web-files/ — reference them in templates
+- Authentication is managed by Power Pages — do not build custom auth
+- Table permissions control data access — configure in Power Pages studio
+- Use `pac pages download` / `pac pages upload` to sync changes
+- Never hardcode environment URLs — use Liquid `{{ request.url }}` helpers
+```
+
+---
+
+##### Code Apps
+
+**What is a Code App?** Code Apps are the newest app type — they let you build a fully custom web app using standard web technologies (React, Vue, or any framework) and host it on Power Platform's managed infrastructure. You get full control over every pixel of the UI and every line of logic, while Power Platform handles authentication, security policies, deployment, and access to 1,500+ data connectors.
+
+**In plain English:** Build a proper website or web app in VS Code the way a developer would — but Microsoft handles all the hosting, security, and login for you, and you can tap into all your existing Power Platform data and connectors.
+
+> **Admin step required first:** Before you can use Code Apps, a Power Platform admin must turn the feature on. Ask your admin to go to: **Power Platform Admin Center → Manage → Environments → [your environment] → Settings → Product → Features → Enable code apps**. End users also need a **Power Apps Premium license**.
+
+```bash
+# Install the Power Apps client library (includes the npm-based CLI)
+npm install @microsoft/power-apps
+
+# Initialize a new code app project
+pac code init --outputDirectory ./my-code-app
+
+# Run locally during development (opens a preview in your browser)
+npm start
+
+# Publish to your Power Platform environment
+pac code push
+
+# Typical folder structure:
+my-code-app/
+  src/
+    index.ts             # App entry point
+    App.tsx              # Root component (if using React)
+    components/          # UI components
+  public/                # Static assets
+  package.json
+  tsconfig.json
+```
+
+> **Note:** Starting with `@microsoft/power-apps` v1.0.4+, a new npm-based CLI is included and will eventually replace `pac code` commands. Check the [npm package](https://www.npmjs.com/package/@microsoft/power-apps) for the latest CLI usage.
+
+**AI instructions file** — create `instructions/codeapp-instructions.md`:
+
+```markdown
+# Code App Instructions
+
+## Type: Power Apps Code App (Code-first web app)
+- Standard web app (React/Vue/TypeScript) hosted on Power Platform
+- Use `@microsoft/power-apps` npm package to access connectors and platform APIs
+- Authentication is handled by Microsoft Entra — do not build custom auth
+- Call Power Platform connectors directly from JavaScript via the client library
+- Publish with `pac code push` — no manual deployment pipeline needed
+- Follows canvas app sharing limits and DLP policies set by admins
+- Not supported in Power Apps mobile app or Power Apps for Windows
+- Use `npm start` for local dev; the platform manages hosting in production
+```
+
+---
+
+#### 4e — Useful PAC CLI Commands Cheat Sheet
+
+**What is this?** A quick-reference card for the most common commands. Bookmark this page — you'll come back to it often. Run these in the VS Code terminal.
+
+```bash
+# Auth
+pac auth create --url https://yourorg.crm.dynamics.com   # Connect to environment
+pac auth list                                             # List saved profiles
+pac auth clear                                            # Remove all profiles
+
+# Solutions
+pac solution list                                         # List solutions in environment
+pac solution clone --name SolutionName --outputDirectory ./solutions
+pac solution push                                         # Push local changes to environment
+pac solution export --name SolutionName --path ./exports  # Export as .zip
+
+# Canvas Apps
+pac canvas unpack --msapp App.msapp --sources ./src
+pac canvas pack   --msapp App.msapp --sources ./src
+
+# PCF Components
+pac pcf init --namespace NS --name MyControl --template field
+pac pcf push --publisher-prefix prefix
+
+# Power Pages
+pac pages download --path ./site --webSiteId <id>
+pac pages upload   --path ./site
+
+# Code Apps
+pac code init --outputDirectory ./my-code-app
+pac code push
+
+# Environment info
+pac env list                                              # List all environments
+pac env who                                               # Show current environment details
+```
+
+---
+
+### Step 5: Install Essential VS Code Extensions
+
+**What is this?** Extensions are add-ons that make VS Code smarter. These are the ones that every developer uses — they catch mistakes as you type, keep your code tidy, and make Git easier to use.
+
+Open VS Code, then open the Extensions panel with `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (macOS). In the search box, type the name of each extension below and click **Install** on the result from the correct publisher.
+
+#### General Development Extensions
+
+| Extension | Purpose |
+|---|---|
+| **ESLint** | Catches code errors as you type — like spell-check but for code |
+| **Prettier - Code formatter** | Automatically formats your code to look clean and consistent when you save |
+| **GitLens** | Shows who changed what and when, directly inside your files. Makes Git much easier to understand |
+| **Error Lens** | Shows error messages directly on the line where the problem is — no hunting around |
+| **Path Intellisense** | Auto-completes file paths as you type them, so you don't have to remember exact folder names |
+
+---
+
+#### GitHub Copilot Prompt-Writing Extensions
+
+**What is this?** These extensions supercharge how you write prompts and interact with Copilot inside VS Code. Install all of them — they work together. If you're using Claude Code instead of Copilot, skip this table but still read the prompting tips below.
+
+| Extension | Publisher | Purpose |
+|---|---|---|
+| **GitHub Copilot** | GitHub | Core AI code completion — shows suggested code in grey as you type; press Tab to accept |
+| **GitHub Copilot Chat** | GitHub | Chat panel for writing prompts in plain English to generate code, explain errors, and refactor |
+| **GitHub Copilot Labs** | GitHub | Experimental extras: translate code between languages, explain code step-by-step, fix bugs with one click |
+| **Prompt Engine** | Microsoft | Helps write, save, and reuse structured prompts directly inside VS Code files |
+| **AI Toolkit for VS Code** | Microsoft | Test and compare prompts against different AI models; useful for fine-tuning how you phrase instructions to Copilot |
+
+**Tips for writing better prompts in Copilot Chat:**
+
+The quality of what the AI builds depends directly on how clearly you describe it. Here is how to get better results:
+
+- **Be specific about the app type and what you want**
+  > ✅ "Create a Canvas App Power Fx formula that filters a gallery by the current user's email"
+  > ❌ "Filter this gallery"
+
+- **Tell the AI what you already have**
+  > "I have a PCF component with an index.ts file. Add a `getValue()` method that returns the current text input value."
+
+- **Ask for step-by-step explanations** — especially useful when learning
+  > "Explain this PAC CLI command step by step: `pac solution clone --name MySolution --outputDirectory ./solutions`"
+
+- **Use `#file` to reference a specific file in your project**
+  > In Copilot Chat, type `#file:canvas-src/Screens/HomeScreen.fx.yaml` to give Copilot context from that exact file before asking your question.
+
+- **Use `/fix`, `/explain`, `/tests` slash commands**
+  > Highlight broken code → open Copilot Chat → type `/fix` → Copilot explains what's wrong and rewrites it.
+
+- **Save your best prompts** — use the Prompt Engine extension to store reusable prompt templates in a `prompts/` folder in your project so the whole team benefits.
+
+---
+
+### Step 6: Choose Your AI Assistant
+
+**What is this?** This is the AI that will actually write the code for you when you describe what you want. You only need **one** of the two options below. Pick the one your team has access to — if you're not sure, ask your manager.
+
+| | GitHub Copilot | Claude Code |
+|---|---|---|
+| **Made by** | GitHub / Microsoft | Anthropic |
+| **Best for** | Teams already on GitHub | Teams using Anthropic's Claude |
+| **What you need** | GitHub account + Copilot subscription | Anthropic API key |
+
+---
+
+#### Option A — GitHub Copilot
+
+**What you need:** A GitHub account with a Copilot subscription (or your organisation's license).
+
+1. In VS Code Extensions (`Ctrl+Shift+X`), search for **GitHub Copilot** and install it
+2. Also install **GitHub Copilot Chat**
+3. Click the **Accounts icon** at the bottom-left of VS Code (it looks like a person silhouette) → **Sign in with GitHub**
+4. A browser window will open — log in to your GitHub account and click **Authorize**
+5. Once signed in, you'll see a chat icon (💬) in the left sidebar — that's Copilot Chat
+
+**How to use it:**
+- **Inline suggestions:** Just start typing code or a comment — Copilot will suggest the rest in grey text. Press `Tab` to accept, or keep typing to ignore it.
+- **Chat panel:** Click the chat icon and type what you want to build in plain English.
+- **Quick ask:** Highlight any code, right-click → **Copilot → Explain This** or **Fix This**.
+
+---
+
+#### Option B — Claude Code
+
+**What you need:** An Anthropic account and API key, or your organisation's Claude Code license.
+
+**Install Claude Code (CLI)** — in the VS Code terminal, run:
+```
+npm install -g @anthropic-ai/claude-code
+```
+
+**Check it installed:**
+```
+claude --version
+```
+
+**Set your API key** (get it from [https://console.anthropic.com](https://console.anthropic.com)):
+```
+export ANTHROPIC_API_KEY="your-api-key-here"
+```
+
+> **Make it permanent** so you don't have to re-run this every time:
+> - **macOS/Linux:** Add the line above to your `~/.zshrc` or `~/.bashrc` file, then run `source ~/.zshrc`
+> - **Windows:** Search for "Environment Variables" in the Start menu → Add a new User variable called `ANTHROPIC_API_KEY` with your key as the value
+
+**Install the VS Code extension:**
+In VS Code Extensions, search for **Claude Code** and install it.
+
+**How to use it:**
+- Open a terminal in your project folder and run: `claude`
+- Or use the Claude Code panel in the VS Code sidebar
+- Type what you want to build in plain English — Claude will read your project files and write code directly
+
+---
+
+### Step 7: Configure VS Code Settings (Recommended)
+
+**What is this?** These settings make VS Code easier and more pleasant to use — auto-save, auto-format, sensible font sizes, and so on. This is a one-time setup.
+
+Go to **File → Preferences → Settings** (or `Ctrl+,` / `Cmd+,`) and apply these settings for a better experience. You can also paste this directly into your `settings.json` file — press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac), type **Open User Settings JSON**, and press Enter. Replace everything in the file with this:
+
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.tabSize": 2,
+  "editor.fontSize": 14,
+  "editor.wordWrap": "on",
+  "editor.minimap.enabled": false,
+  "terminal.integrated.fontSize": 13,
+  "files.autoSave": "onFocusChange",
+  "explorer.confirmDelete": false,
+  "editor.inlineSuggest.enabled": true,
+  "github.copilot.enable": {
+    "*": true
+  }
+}
+```
+
+> Remove the `"github.copilot.enable"` block if you're using Claude Code instead of Copilot.
+
+---
+
+## ✅ Part 1 Checklist
+
+Before moving on, confirm you have all of these:
+
+- [ ] VS Code is installed and opens without errors
+- [ ] `node --version` prints a version number in the terminal
+- [ ] `npm --version` prints a version number in the terminal
+- [ ] `git --version` prints a version number in the terminal
+- [ ] `pac --version` prints a version number in the terminal
+- [ ] Power Platform Tools extension is installed in VS Code
+- [ ] `pac auth list` shows your work account logged in
+- [ ] General extensions (ESLint, Prettier, GitLens, Error Lens, Path Intellisense) are installed
+- [ ] GitHub Copilot OR Claude Code is installed and signed in
+
+If any box is unchecked, go back to that step before continuing.
+
+---
+
+## Part 2 — Project Directory Setup
+
+**What is this?** Every time you start working on a new app (or pick up an existing one), you set up a project folder. This section walks you through exactly that. It takes about 5 minutes once you've done it a couple of times.
+
+Do these steps **every time you start a new project** or clone an existing one.
+
+---
+
+### Step 1: Create or Clone Your Project
+
+**What does this mean?** You need a folder on your computer where all your project files will live. You either create a brand-new empty one, or "clone" (download) an existing project from GitHub.
+
+**Starting a new project** — in the VS Code terminal:
+```
+mkdir my-project-name
+cd my-project-name
+```
+
+> `mkdir` creates the folder. `cd` means "change directory" — it moves the terminal into that folder. Replace `my-project-name` with whatever you want to call your project (no spaces — use hyphens instead).
+
+**Cloning an existing project from GitHub** (if someone has already started the project):
+```
+git clone https://github.com/your-org/your-repo.git
+cd your-repo
+```
+
+> Your team lead or IT team will give you the GitHub URL to use.
+
+Then open the folder in VS Code:
+```
+code .
+```
+
+> The `.` means "this folder". This command opens the current folder as a VS Code workspace.
+
+---
+
+### Step 2: Initialize Git (new projects only)
+
+**What is this?** If you created a brand new folder (not cloned), you need to turn on Git's tracking for that folder. This only takes one command.
+
+```
+git init
+```
+
+You should see: `Initialized empty Git repository in .../your-folder/.git/`
+
+---
+
+### Step 3: Create a `.gitignore` File
+
+**What is this?** Some files should never be uploaded to GitHub — passwords, large auto-generated folders, and personal settings. A `.gitignore` file tells Git to skip these automatically.
+
+In VS Code, create a new file in your project folder called `.gitignore` (exactly that name, including the dot at the start). Paste this content inside it:
+
+```
+# Dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# Environment variables (NEVER commit these)
+.env
+.env.local
+.env.*.local
+
+# Build outputs
+dist/
+build/
+out/
+.next/
+
+# Editor files
+.vscode/
+.idea/
+*.swp
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+```
+
+> **How to create a new file in VS Code:** In the left sidebar (Explorer panel), hover over your project folder name and click the "New File" icon (it looks like a page with a +). Type the filename and press Enter.
+
+---
+
+### Step 4: Create a `.env` File (for secrets and config)
+
+**What is this?** A `.env` file stores sensitive values like passwords, API keys, and database URLs. Keeping them here — instead of hardcoding them in your code — means they never accidentally get shared or published. This is a standard security practice.
+
+Create a new file in your project folder called `.env` and paste this as a starting template:
+
+```
+# .env — DO NOT commit this file to Git
+DATABASE_URL=your-database-url-here
+API_KEY=your-api-key-here
+APP_PORT=3000
+```
+
+Replace the placeholder values with your real ones as your project grows. The `.gitignore` file from Step 3 already prevents `.env` from being uploaded to GitHub — this is intentional.
+
+---
+
+### Step 5: Install Project Dependencies
+
+**What is this?** Most projects rely on a set of pre-built libraries (other people's code) to function. These are listed in a file called `package.json`. This one command reads that file and downloads everything the project needs.
+
+If the project has a `package.json` file (most JavaScript/TypeScript projects do), run:
+```
+npm install
+```
+
+This creates a `node_modules/` folder — that is normal. It is large, but your `.gitignore` already excludes it from Git, so it won't be uploaded.
+
+> **Nothing happened?** If there's no `package.json` yet (brand new project), that's fine — skip this step and come back when the AI generates one for you.
+
+---
+
+### Step 6: Add an AI Context File (Highly Recommended)
+
+**What is this?** This file tells your AI assistant about your project — what it does, what technology it uses, and what coding style to follow. Without this, the AI gives generic answers. With it, every suggestion is tailored to your exact project. This is one of the most important things you can do to get better AI output.
+
+**For GitHub Copilot** — create the folder and file:
+```
+mkdir -p .github
+```
+
+Then in VS Code, create `.github/copilot-instructions.md` with content like this:
+
+```markdown
+# Project: [Your Project Name]
+
+## What this project does
+[One paragraph describing what the app does]
+
+## Tech stack
+- Framework: React / Next.js / Vue / etc.
+- Language: TypeScript / JavaScript
+- Styling: Tailwind CSS / CSS Modules / etc.
+- Database: PostgreSQL / MongoDB / etc.
+
+## Coding conventions
+- Use functional components (no class components)
+- Use async/await (not .then() chains)
+- All functions must have TypeScript types
+- File names use kebab-case (e.g. user-profile.tsx)
+
+## Folder structure
+src/
+  components/   # Reusable UI components
+  pages/        # Page-level components
+  utils/        # Helper functions
+  types/        # TypeScript type definitions
+```
+
+**For Claude Code** — create `CLAUDE.md` in your project root with the same kind of content. Claude Code reads this file automatically every time you start a session.
+
+> **Tip:** Ask your AI assistant to help you write these files! Type: *"Based on this project's files, write a CLAUDE.md that describes what this project does, its tech stack, and coding conventions."*
+
+---
+
+### Step 7: Verify Everything Works
+
+**What is this?** A final sanity check before you start building. Run these commands in the terminal and confirm each one gives a sensible response.
+
+```bash
+# Check Node is available
+node --version
+
+# Check npm is available
+npm --version
+
+# Check Git is set up
+git status
+
+# Start the development server (if applicable)
+npm run dev
+```
+
+If `npm run dev` works and you see your app in the browser — you're ready to build! 🎉
+
+> **`git status` says "not a git repository"?** Run `git init` first (see Step 2 above).
+> **`npm run dev` gives an error?** Run `npm install` first (see Step 5), then try again.
+
+---
+
+## 🚀 Your First Vibe Coding Session — A Walkthrough
+
+**You're set up. Now what?** Here is exactly what your first session looks like, step by step.
+
+1. **Create your project** by running `npx create-powerapp` in the terminal and answering the four questions. VS Code will open automatically when it's done.
+2. **Open the terminal** in VS Code (`Ctrl+` `` ` `` or `Cmd+` `` ` ``)
+3. **Open `prompts/starter.md`** in VS Code — this file has ready-made prompts for your app type. You can use these directly or write your own.
+4. **Open your AI assistant** — click the Copilot Chat icon (💬) or run `claude` in the terminal
+5. **Describe what you want to build** — either copy a prompt from `prompts/starter.md` or write your own. Be specific. For example:
+
+   > *"I'm building a Canvas App for employee time-off requests. Create a screen with a date range picker, a dropdown for leave type (Annual, Sick, Personal), a text box for notes, and a Submit button. When submitted, save the record to a Dataverse table called cr123_LeaveRequests."*
+
+6. **Review what the AI writes.** You don't need to understand every line — just check it looks roughly right and run it to see if it works
+7. **Test it.** If something looks wrong, describe the problem to the AI: *"The submit button isn't doing anything when I click it. Can you fix it?"*
+8. **Save your work** when you're happy with a chunk:
+
+   ```
+   git add .
+   git commit -m "Added leave request submission form"
+   git push
+   ```
+
+That's it. Repeat steps 5–8 for every feature you want to add.
+
+---
+
+## Quick Reference — Daily Workflow
+
+Once everything is set up, your typical day looks like this:
+
+```
+1. Open VS Code → open your project folder
+2. Open the terminal (Ctrl+` or Cmd+`)
+3. Start the dev server: npm run dev
+4. Open Copilot Chat or Claude Code
+5. Describe what you want to build → review the AI's code → accept or adjust
+6. Save your work: git add . → git commit -m "describe what you did" → git push
+```
+
+---
+
+## Troubleshooting
+
+**Don't panic when things go wrong — errors are normal, even for experienced developers.** The AI assistant can help you fix them. Copy the error message and paste it into the chat with: *"I got this error — what does it mean and how do I fix it?"*
+
+| Problem | Fix |
+|---|---|
+| `npm: command not found` | Re-install Node.js from nodejs.org, then restart VS Code |
+| `git: command not found` | Install Git (see Part 1, Step 3) |
+| `pac: command not found` | Run `npm install -g pac` or restart VS Code after install |
+| `pac auth create` browser doesn't open | Run `pac auth create --url <url> --deviceCode` for device-code login instead |
+| Canvas App changes not showing after push | Run `pac solution push --force-overwrite` |
+| PCF component won't build | Delete `node_modules/` and re-run `npm install` |
+| Copilot not suggesting anything | Check you're signed into GitHub in VS Code (bottom-left Accounts icon) |
+| Copilot Chat `#file` not working | Make sure the file is inside the currently open VS Code workspace folder |
+| `ANTHROPIC_API_KEY` not found | Re-run the export command or add to shell config (see Step 6, Option B) |
+| `node_modules` missing | Run `npm install` in the project folder |
+| Port already in use | Run `npm run dev -- --port 3001` to use a different port |
+| "I have no idea what this error means" | Copy the full error text → paste into Copilot Chat or Claude → ask "what does this mean and how do I fix it?" |
+
+---
+
+## Getting Help
+
+- **GitHub Copilot docs:** https://docs.github.com/en/copilot
+- **Claude Code docs:** https://docs.anthropic.com/en/docs/claude-code
+- **PAC CLI reference:** https://learn.microsoft.com/en-us/power-platform/developer/cli/reference
+- **Power Platform Tools extension:** https://marketplace.visualstudio.com/items?itemName=microsoft-IsvExpTools.powerplatform-vscode
+- **PCF (Code Components) docs:** https://learn.microsoft.com/en-us/power-apps/developer/component-framework/overview
+- **Code Apps docs:** https://learn.microsoft.com/en-us/power-apps/developer/code-apps/overview
+- **Canvas App Power Fx reference:** https://learn.microsoft.com/en-us/power-platform/power-fx/formula-reference
+- **Power Pages docs:** https://learn.microsoft.com/en-us/power-pages/
+- **VS Code keyboard shortcuts:** Press `Ctrl+K Ctrl+S` (or `Cmd+K Cmd+S`) inside VS Code
+- **Ask your AI assistant directly** — type "explain this error" or "how do I…" in the chat panel
+
+---
+
+*Last updated: May 2026*