docs: refine downstream onboarding workflow

docs/collaboration-playbook.md

@@ -39,7 +39,7 @@ Onboarding should explicitly set:
 Onboarding should use `docs/downstream-onboarding-playbook.md`, not a blind
 repo copy.
 
-- vendor the template snapshot into `.minions-template/`
+- vendor an export-ready template snapshot into `.minions-template/` with `.git/` and `do-not-export` files excluded
 - export the live operating files using `docs/export-manifest.md`
 - manually merge `INIT.md`, `MEMORY.md`, `docs/operator-onboarding-checklist.md`, and `minion-version.md`
 - commit the vendored snapshot and exported live state together as the initial baseline
@@ -49,8 +49,8 @@ repo copy.
 Use `PM` as the default owner for downstream template upgrades.
 
 - onboarding should establish `.minions-template/` first; upgrades depend on that baseline
-- keep the approved template snapshot in `.minions-template/`
-- stage the incoming template in a temporary path such as `.minions-template.next/`
+- keep the approved export-ready template snapshot in `.minions-template/`
+- stage the incoming export-ready template in a temporary path such as `.minions-template.next/`
 - compare old template, new template, and live downstream files before changing production minion docs
 - use `docs/export-manifest.md` to decide whether each file is replaced, manually merged, or left downstream-owned
 - update the downstream base template version only after the live files and vendored snapshot both match the approved upgrade

docs/downstream-onboarding-playbook.md

@@ -27,6 +27,14 @@ This gives AI agents a durable provenance model:
 Do not stage onboarding from `.minions-template.next/`; that path is for later
 upgrade candidates.
 
+The vendored snapshot is an export-ready copy of the template, not a full Git
+clone.
+
+- exclude `.git/`
+- exclude files marked `do-not-export` in `docs/export-manifest.md`
+- `.mm.md` should not appear in `.minions-template/` unless the Operator
+  intentionally chooses to carry MM context downstream
+
 ## Ownership
 
 - `PM` owns the onboarding export packet and Operator-facing checklist
@@ -40,7 +48,10 @@ upgrade candidates.
 
 ## Onboarding Workflow
 
-1. Copy the template repo into `.minions-template/` unchanged.
+1. Create `.minions-template/` as an export-ready snapshot of the template:
+   - copy the files needed for onboarding and future upgrades
+   - do not carry Git metadata such as `.git/`
+   - do not carry `do-not-export` files such as `.mm.md`
 2. Review `docs/export-manifest.md` before exporting any live files.
 3. Export `template-replace` files from `.minions-template/` into the live
    downstream repo.
@@ -50,8 +61,8 @@ upgrade candidates.
    - `MEMORY.md`
    - `docs/operator-onboarding-checklist.md`
    - `minion-version.md`
-5. Do not export `do-not-export` files such as `.mm.md` unless the Operator
-   explicitly wants them downstream.
+5. Do not export `do-not-export` files, and do not keep them in the vendored
+   snapshot, unless the Operator explicitly wants them downstream.
 6. Treat downstream-owned files as project surfaces, not template clones:
    - project `README.md`
    - live plans
@@ -94,6 +105,7 @@ upgrade candidates.
 
 - template version being onboarded
 - vendored snapshot path
+- confirmation that `.git/` and `do-not-export` files were excluded from the vendored snapshot
 - files exported directly from template
 - files manually merged for downstream use
 - files intentionally left downstream-owned

docs/downstream-upgrade-playbook.md

@@ -25,6 +25,12 @@ first upgrade should establish one that matches the repo's current base-template
 version before attempting a larger template jump. If the repo is truly new,
 run the onboarding playbook first.
 
+Both snapshot paths should contain export-ready copies of the template, not full
+Git clones.
+
+- exclude `.git/`
+- exclude files marked `do-not-export` in `docs/export-manifest.md`
+
 ## Ownership
 
 - `PM` owns the upgrade packet, merge order, and Operator-facing decision
@@ -41,9 +47,10 @@ run the onboarding playbook first.
 
 1. Confirm the downstream repo's current base-template version in
    `minion-version.md`.
-2. Stage the current approved template snapshot in `.minions-template/` if it is
-   not already present.
-3. Import the incoming template version into `.minions-template.next/`.
+2. Stage the current approved export-ready template snapshot in
+   `.minions-template/` if it is not already present.
+3. Import the incoming template version into `.minions-template.next/` using the
+   same export-ready filtering rules.
 4. Diff `.minions-template/` against `.minions-template.next/` to see what the
    template changed.
 5. Use `docs/export-manifest.md` to classify each affected live file as:

docs/export-manifest.md

@@ -14,8 +14,19 @@ Use this manifest with:
   consciously reapply any intentional downstream divergence
 - `manual-merge`: always review and merge with downstream state
 - `downstream-owned`: do not overwrite during template upgrades
-- `do-not-export`: keep in the template repo only unless the Operator explicitly
-  chooses otherwise
+- `do-not-export`: keep out of downstream live files and out of the vendored
+  `.minions-template/` snapshot unless the Operator explicitly chooses
+  otherwise
+
+## Vendored Snapshot Rule
+
+`.minions-template/` is an export-ready snapshot, not a full clone of the
+template repo.
+
+- exclude `.git/`
+- exclude all `do-not-export` files
+- keep only the files needed to onboard and later upgrade downstream minion
+  workflow
 
 ## Manifest
 

docs/operator-onboarding-checklist.md

@@ -33,7 +33,7 @@ Date: YYYY-MM-DD
 - `CHANGELOG.md` initialized and owner set
 - `ROADMAP.md` initialized and owner set
 - `TODO.md` initialized and owner set
-- vendored template snapshot initialized (recommended `.minions-template/`)
+- vendored template snapshot initialized (recommended `.minions-template/`; exclude `.git/` and `do-not-export` files)
 - initial downstream export completed using `docs/downstream-onboarding-playbook.md`
 - downstream template-upgrade owner confirmed (default `PM`)
 - `minion-version.md` reviewed and downstream version format confirmed