Fix agent onboarding doc gaps: missing CONTRIBUTING.md, broken link, missing examples

CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+Thanks for helping improve the PSModule documentation. Everything here is a work in progress — if you find a
+problem, fix it if it's small, or open an issue if it needs more discussion.
+
+## Repository layout
+
+- `src/docs/`: the documentation source, built as a [Zensical](https://zensical.org/) site.
+- `src/includes/`, `src/overrides/`: shared snippets and theme customizations for the site.
+- `src/zensical.toml`: site configuration and navigation.
+- `guidance/`: example PowerShell snippets referenced from the docs.
+
+## Making changes
+
+1. Create a worktree/branch for your change (see [Git Worktrees](https://msxorg.github.io/docs/Ways-of-Working/Git-Worktrees/)).
+2. Edit the relevant page(s) under `src/docs/`. Update `src/zensical.toml` navigation if you add or move a page.
+3. Open a draft pull request early and push small, incremental commits so the change is easy to review.
+4. Merge to `main` once review passes. The `Docs` workflow (`.github/workflows/Docs.yml`) builds and publishes the
+   site to GitHub Pages on every merge to `main`.
+
+## Building and previewing locally
+
+```powershell
+pip install zensical
+cd src
+zensical build --clean
+```
+
+The built site is written to `src/site/`. See the [Zensical docs](https://zensical.org/docs/setup/basics/) for
+live-reloading preview options.
+
+## Linting
+
+Pull requests are linted with [super-linter](https://github.com/super-linter/super-linter) via the `Docs` workflow.
+Keep Markdown changes consistent with the surrounding style and fix any linter findings reported on the PR.

src/docs/Modules/Repository-Defaults.md

@@ -54,7 +54,7 @@ Local work should use the organization worktree convention:
 - `main/` tracks the default branch.
 - Feature worktrees use `<type>-<slug>` directories and `<type>/<slug>` branches.
 
-For branch and worktree details, see [Git Worktrees](../../Ways-of-Working/Git-Worktrees.md).
+For branch and worktree details, see [Git Worktrees](https://msxorg.github.io/docs/Ways-of-Working/Git-Worktrees/).
 
 ## Default repository layout
 
@@ -138,6 +138,34 @@ Every repository must be usable by an agent that has never seen it before, witho
 
 These files are the agent equivalent of the README: pointers, not copies. Keep them short so the linked documentation stays the single source of truth. Like the other governance files, they live in the repository itself so it can stand on its own.
 
+### Example
+
+`AGENTS.md`:
+
+```markdown
+# Agents
+
+This repository is a PowerShell module built with the [PSModule](https://github.com/PSModule) framework.
+
+- Read this repository's own [README](README.md) and [CONTRIBUTING](CONTRIBUTING.md) first.
+- For module layout, build/test/pack/publish behavior, and repository conventions, see
+  [PSModule/docs](https://psmodule.io/docs/), starting with
+  [Process-PSModule](https://psmodule.io/docs/Modules/Process-PSModule/).
+- For org-wide coding standards and ways of working, see [MSXOrg/docs](https://msxorg.github.io/docs/).
+```
+
+`CLAUDE.md`:
+
+```markdown
+@AGENTS.md
+```
+
+`.github/copilot-instructions.md`:
+
+```markdown
+Follow the instructions in [AGENTS.md](../AGENTS.md).
+```
+
 ## Managed file distribution
 
 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.