Refactor agent onboarding documentation and clarify managed file distribution process

Author: MariusStorhaug

AGENTS.md

@@ -1,19 +1,29 @@
 # Agents
 
-This repository holds the source for the [PSModule](https://psmodule.io) documentation, published at [psmodule.io/docs](https://psmodule.io/docs). Everything an agent needs to work here is documentation — read it the same way a new contributor would.
+## Main directive
 
-## Start here
+Everything is a work in progress and can be updated and improved.
+If you find a problem, fix it if it's small; otherwise, register it as an issue in the respective repo.
 
-1. Read this file, then the [README](README.md) for what this repository is and how it builds.
-2. Read the [PSModule documentation](https://psmodule.io/docs) for the framework's why, how, and what — its standards, conventions, and style guides. The source for those pages lives under `src/docs/` in this repository.
-3. Read the [MSX documentation](https://msxorg.github.io/docs) for the organization-level principles and ways of working that sit above any single repository.
+## Install the ecosystem
 
-## Working in this repository
+1. Create a folder in the home directory called `.msx/PSModule`:
+2. Clone the ecosystem locally:
+   1. <https://github.com/PSModule/docs> — requires PRs to be updated.
+      - Clone as bare and use worktrees.
+      - Create a worktree for all branches - worktree = name of the branch.
+   2. <https://github.com/PSModule/memory> — work directly towards main.
+      - Simple clone, only main.
 
-- Documentation pages live under `src/docs/`; the published site navigation is defined in `src/zensical.toml`. Add a new page to both.
-- The PowerShell standards and style guides under `src/docs/` are the source of truth for content changes — follow the page you are changing.
-- Keep each page the single source of truth: link to the canonical page instead of restating its content elsewhere.
+To install:
+ Clone the repos in the users home folder under a sub-folder named `.msx/PSModule`.
+- Set configs locally to each of these repos using the github username and email.
 
-## The rule
+## Working with the ecosystem
 
-This file points; it never defines. Standards and process live in the documentation and are referenced by their canonical location — never copied here.
+1. Get to know this repo first:
+   - [README](README.md) for what this repository is and how it builds.
+   - [CONTRIBUTING](CONTRIBUTING.md) for how to contribute and the review process.
+2. Read the `.msx/PSModule/main/docs` - start with the index to get an overview of what is here.
+3. Read the `.msx/PSModule/memory` - start with the index to get an overview of what is here. Use this while working - commit your memories here for work inside the PSModule organization.
+4. While working with the code, do small micro commits and push on every commit. This will make it easier to review and merge your changes.

src/docs/Modules/Repository-Defaults.md

@@ -140,22 +140,30 @@ These files are the agent equivalent of the README: pointers, not copies. Keep t
 
 ## Managed file distribution
 
-Shared files should be treated as managed files. The current distribution service is [`PSModule/Distributor`](https://github.com/PSModule/Distributor). It keeps source file sets under `Repos/{Type}/{Selection}/` and syncs those files into repositories through pull requests.
+Shared repository files are managed through [`PSModule/Distributor`](https://github.com/PSModule/Distributor). Distributor is the source of truth for managed file content and file-set membership.
 
-The current Distributor model is subscription-based:
+Managed-file distribution follows this contract:
 
-- `Type` is an organization repository custom property that maps a repository to a type folder such as `Module` or `Action`.
-- `SubscribeTo` is an organization repository custom property that selects file sets such as `dependabot.yml`, `Linter Settings`, `PSModule Settings`, `CODEOWNERS`, `License`, `.gitattributes`, and `.gitignore`.
-- Sync changes are delivered through a `managed-files/update` branch and a `⚙️ [Maintenance]: Sync managed files` pull request.
-- Managed files are overwritten by the source file set. Local edits to managed files should be made in Distributor, not directly in the receiving repository.
-- Removing a file from a Distributor file set does not delete the previously distributed file from target repositories; cleanup is explicit.
+- `Type` maps a repository to its file-set root (for example `Module` or `Action`).
+- `SubscribeTo` declares which optional managed file sets the repository receives.
+- Organization-wide mandatory file sets define non-optional governance and supply-chain files for each applicable repository type.
+- Distributor delivers changes through a `managed-files/update` branch and a `⚙️ [Maintenance]: Sync managed files` pull request.
+- Receiving repositories treat managed files as generated artifacts from Distributor. Local edits in the receiving repository are replaced on the next sync and must be made in Distributor instead.
+- Removing a file from a file set does not implicitly delete previously synced copies; deletion is an explicit managed change.
 
-Two follow-up Distributor capabilities define the desired direction:
+This page defines what files must exist in repositories. Distributor defines how those files are distributed and kept aligned.
 
-- **Global file sets** should allow common file sets such as `.gitattributes`, `.gitignore`, and `License` to be defined once and made available to all repository types while still requiring subscription.
-- **Mandatory file sets** should allow organization-critical files such as `SECURITY.md`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, and supply-chain configuration to be pushed to applicable repositories without each repository having to subscribe manually.
+### Migration for existing repositories
 
-Until mandatory file sets exist, repository owners are still responsible for ensuring the required common files exist. Distributor is the preferred implementation mechanism; this document is the standard that says what must exist and why.
+Repositories that still reflect older distribution behavior should be aligned to this contract:
+
+1. Set or correct repository `Type` and `SubscribeTo` properties.
+2. Ensure mandatory governance and supply-chain files from this standard exist in the repository.
+3. Move any intended local edits in managed files into Distributor source file sets.
+4. Sync from Distributor and merge the `managed-files/update` pull request.
+5. Remove unmanaged duplicates or stale files explicitly when they are no longer part of an active file set.
+
+After migration, the repository keeps the required files from this standard, and managed-file content changes are made through Distributor-first updates.
 
 ## Supply-chain defaults