refactor: clarify sync workflow and merge guidelines in documentation

Author: Hjaf

.github/agents/sync-upstream.agent.md

@@ -13,7 +13,7 @@ You synchronize this Equinor-aligned fork with the upstream `microsoft/power-pla
 
 1. **Equinor content is sacred.** Sections, guardrails, references, and review records added for Equinor alignment must never be silently overwritten. When upstream changes a file that contains Equinor-specific content, merge intelligently — incorporate new upstream information while preserving Equinor additions.
 
-2. **Context from history.** Always inspect `git log` for upstream commits to understand the *intent* behind changes, not just the diff. Commit messages, PR titles, and change patterns inform how to merge.
+2. **Context from history.** Always inspect `git log` for upstream commits to understand the _intent_ behind changes, not just the diff. Commit messages, PR titles, and change patterns inform how to merge.
 
 3. **PR-based output.** All changes land on a `sync/upstream-YYYY-MM-DD` branch and are submitted as a pull request for human review. Never push directly to `main`.
 
@@ -38,6 +38,7 @@ Read before starting any sync:
 
 ## Guardrails
 
+- **Never create, push, or submit pull requests to the upstream `microsoft/power-platform-skills` repository.** All PRs target `origin` (the Equinor fork) only. This workflow is one-way: pull FROM upstream, PR into the fork's `main`.
 - Do not overwrite `docs/equinor-alignment/**` with upstream content.
 - Do not remove Equinor-specific sections from READMEs, AGENTS.md, shared docs, or scripts.
 - Do not merge upstream changes that introduce production-system interaction without flagging for owner review.

.github/copilot-instructions.md

@@ -84,13 +84,13 @@ git log --oneline --no-merges $(git merge-base HEAD upstream/main)..upstream/mai
 git diff --name-status $(git merge-base HEAD upstream/main)..upstream/main -- plugins/
 ```
 
-Use the `sync-upstream` skill or the **Upstream Sync Agent** for guided PR-based synchronization. The workflow:
+Use the `sync-upstream` skill or the **Upstream Sync Agent** for guided PR-based synchronization. The workflow is **one-way** (pull FROM upstream, PR into the Equinor fork's `main`). Never create or submit pull requests to the upstream `microsoft/power-platform-skills` repository.
 
 1. Creates a `sync/upstream-YYYY-MM-DD` branch
 2. Analyzes upstream git history for context
 3. Merges changes while preserving Equinor-specific content
 4. Triggers plugin re-reviews for affected reviewed plugins
-5. Opens a pull request for human review
+5. Opens a pull request on the Equinor fork for human review
 
 ## PR and Code Review
 

.github/skills/sync-upstream/SKILL.md

@@ -11,6 +11,8 @@ model: opus
 
 Synchronize changes from `microsoft/power-platform-skills` into this fork via a **pull request** on a dedicated sync branch. Never merge directly to `main`.
 
+**Direction:** This workflow pulls FROM upstream INTO this fork. Never create, push, or submit pull requests TO the upstream `microsoft/power-platform-skills` repository. All PRs target `origin` (the Equinor fork) only.
+
 Default to read-only discovery. Do not apply changes until the user approves the sync plan.
 
 ## Inputs
@@ -107,13 +109,13 @@ Also inspect shared dependencies: `shared/`, `scripts/`, `.claude-plugin/marketp
 
 Classify every changed file into one of these categories:
 
-| Category | Criteria | Action |
-| --- | --- | --- |
-| **Direct copy** | File has no Equinor-specific content and is fully upstream-owned | Copy from upstream |
-| **Intelligent merge** | File contains both upstream content and Equinor sections (READMEs, AGENTS.md, shared docs, workflows) | Merge preserving Equinor content |
-| **Equinor-only** | File is entirely Equinor-created (`docs/equinor-alignment/**`, review records, `.github/skills/`, `.github/agents/`) | Never overwrite — skip |
-| **Review required** | File contains scripts, hooks, `.mcp.json`, or production-interaction patterns | Defer until inspected |
-| **New file** | File does not exist locally | Copy from upstream (new content) |
+| Category              | Criteria                                                                                                             | Action                           |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| **Direct copy**       | File has no Equinor-specific content and is fully upstream-owned                                                     | Copy from upstream               |
+| **Intelligent merge** | File contains both upstream content and Equinor sections (READMEs, AGENTS.md, shared docs, workflows)                | Merge preserving Equinor content |
+| **Equinor-only**      | File is entirely Equinor-created (`docs/equinor-alignment/**`, review records, `.github/skills/`, `.github/agents/`) | Never overwrite — skip           |
+| **Review required**   | File contains scripts, hooks, `.mcp.json`, or production-interaction patterns                                        | Defer until inspected            |
+| **New file**          | File does not exist locally                                                                                          | Copy from upstream (new content) |
 
 **Protected paths — never direct-copy without explicit approval:**
 
@@ -141,6 +143,7 @@ git checkout upstream/main -- <path>
 For files requiring merge, follow this process:
 
 1. **Read the upstream version:**
+
    ```bash
    git show upstream/main:<path>
    ```
@@ -221,6 +224,7 @@ Merge strategy: direct-copy (<n>), intelligent-merge (<n>), deferred (<n>)"
 ```
 
 If the changeset is large, split into multiple commits by category:
+
 - `sync: direct-copy upstream files` — for files taken as-is
 - `sync: merge upstream changes preserving Equinor content` — for intelligently merged files
 - `sync: update review records for affected plugins` — for review record updates
@@ -233,6 +237,8 @@ git push origin sync/upstream-$(date +%Y-%m-%d)
 
 #### 5.3 Create Pull Request
 
+The PR targets `origin` (the Equinor fork), merging the sync branch into `main`. Never target the upstream Microsoft repository.
+
 ```bash
 gh pr create \
   --base main \
@@ -291,17 +297,19 @@ To make future syncs easier, when adding Equinor-specific content to upstream fi
 
 ```markdown
 <!-- equinor-start: description of addition -->
+
 Equinor-specific content here...
+
 <!-- equinor-end -->
 ```
 
 This allows the sync workflow to reliably identify and preserve Equinor sections during intelligent merges.
 
 ## Naming Convention
 
-| Pattern | Example |
-| --- | --- |
-| Branch | `sync/upstream-2026-05-28` |
-| Branch (same-day duplicate) | `sync/upstream-2026-05-28-2` |
-| Commit prefix | `sync:` |
-| PR title | `sync: upstream microsoft/power-platform-skills 2026-05-28` |
+| Pattern                     | Example                                                     |
+| --------------------------- | ----------------------------------------------------------- |
+| Branch                      | `sync/upstream-2026-05-28`                                  |
+| Branch (same-day duplicate) | `sync/upstream-2026-05-28-2`                                |
+| Commit prefix               | `sync:`                                                     |
+| PR title                    | `sync: upstream microsoft/power-platform-skills 2026-05-28` |