docs(specs): add v1 spec and upgrade Process-PSModule caller to v8

.github/pull_request_template.md

@@ -0,0 +1,36 @@
+<!-- markdownlint-disable MD041 -->
+<!--
+This description becomes the release note. Write it for users of the module, not for reviewers.
+
+Title: <Icon> [<Type>]: <User-facing outcome>
+  🌟 [Major] · 🚀 [Feature] · 🩹 [Patch] · 🪲 [Fix] · 📖 [Docs] · ⚙️ [Maintenance]
+
+Apply the matching label: Major, Minor, Patch, or NoRelease.
+Full format: https://msxorg.github.io/docs/Ways-of-Working/PR-Format/
+
+Delete the comments and any unused section before marking the pull request ready.
+-->
+
+<!-- One paragraph, present tense, describing what changes for the user. -->
+
+## New: <capability>
+
+<!--
+What the user can now do, what they need to do differently, and an example.
+Use the section headers that fit the change and delete the rest:
+  ## Breaking Changes   - what stopped working or changed incompatibly (Major only)
+  ## New: <capability>  - new things the user can do
+  ## Changed: <behavior> - existing behavior that now works differently
+  ## Fixed: <problem>   - problems now resolved
+-->
+
+## Technical Details
+
+<!-- For reviewers: files touched, design decisions, migration notes. Delete this section if there is nothing noteworthy. -->
+
+<details>
+<summary>Related issues</summary>
+
+<!-- Use fully qualified references, for example: Fixes PSModule/Repo#123 -->
+
+</details>

.github/workflows/Process-PSModule.yml

@@ -4,6 +4,9 @@
   workflow_dispatch:
   schedule:
     - cron: '0 0 * * *'
+  push:
+    branches:
+      - main
   pull_request:
     branches:
       - main
@@ -13,19 +16,22 @@
       - reopened
       - synchronize
       - labeled
+      - unlabeled
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
-permissions:
-  contents: write
-  pull-requests: write
-  statuses: write
-  pages: write
-  id-token: write
+permissions: {}
 
 jobs:
   Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@205d193f34cbbaf9992955c21d842bcf98a1859f # v5.4.6
-    secrets: inherit
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    secrets:
+      PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
+      GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
+      GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}

.gitignore

@@ -14,6 +14,9 @@
 # PSModule framework outputs folder
 outputs/*
 
+# Zensical generated site
+docs/site/
+
 # .Net build output
 bin/
 obj/

AGENTS.md

@@ -0,0 +1,31 @@
+# Agents
+
+## Main directive
+
+Everything is a work in progress and can be improved.
+If you find a problem or improvement, fix if small; otherwise open an issue.
+
+## Repo guidance
+
+- [`README.md`](README.md) — what this module is and how to use it.
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to contribute to this repository.
+
+## PSModule Framework guidance
+
+For PSModule-specific build, layout, and process guidance:
+
+- [Template quickstart](https://psmodule.github.io/docs/Modules/Process-PSModule/template-quickstart/)
+- [Repository defaults](https://psmodule.github.io/docs/Modules/Repository-Defaults/)
+- [Module anatomy](https://psmodule.github.io/docs/Modules/Process-PSModule/module-anatomy/)
+- [Build, test, pack, publish](https://psmodule.github.io/docs/Modules/Process-PSModule/build-test-pack-publish/)
+- [Standards](https://psmodule.github.io/docs/Modules/Standards/)
+- [PSModule/memory](https://github.com/PSModule/memory)
+
+## Org-wide guidance
+
+For cross-cutting ways of working and standards:
+
+- [Agentic Development](https://msxorg.github.io/docs/Ways-of-Working/Agentic-Development/)
+- [Ways of Working](https://msxorg.github.io/docs/Ways-of-Working/)
+- [Coding Standards](https://msxorg.github.io/docs/Coding-Standards/)
+- [MSXOrg/memory](https://github.com/MSXOrg/memory)

CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+Thank you for contributing to this module.
+Read [`AGENTS.md`](AGENTS.md) first for the full guidance chain and documentation references.
+
+## Before you start
+
+1. Read [`README.md`](README.md) to understand what the module does.
+2. Familiarise yourself with the [repository defaults](https://psmodule.github.io/docs/Modules/Repository-Defaults/) that this repository must satisfy.
+3. Check the open issues and pull requests to avoid duplicate work.
+
+## Workflow
+
+This project follows the [MSXOrg contribution workflow](https://msxorg.github.io/docs/Ways-of-Working/Contribution-Workflow/):
+
+1. Open or pick up an issue that describes the change.
+2. Create a branch from `main` following the `<type>/<issue>-<short-slug>` convention (e.g. `feat/42-add-security-md`).
+3. Make small, focused commits and push often.
+4. Open a **draft PR** as soon as the change has a basic shape — early feedback is preferred.
+5. Run the **Copilot review loop**: request a Copilot review, address its feedback, and repeat until it reports a clean round. File an issue for any out-of-scope findings rather than expanding the PR.
+6. Mark the PR ready for review and enable auto-merge. It lands automatically once the required checks pass and a reviewer approves.
+
+For branching details, see [Branching and Merging](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/).
+
+## Pull requests
+
+- Keep PRs small and focused on a single deliverable.
+- The PR title should follow the [commit conventions](https://msxorg.github.io/docs/Ways-of-Working/Commit-Conventions/).
+
+For PR format guidance, see [PR Format](https://msxorg.github.io/docs/Ways-of-Working/PR-Format/).
+
+## Issues
+
+Use GitHub Issues to report bugs, request features, or propose improvements.
+Follow the [issue format](https://msxorg.github.io/docs/Ways-of-Working/Issue-Format/) guidance.
+
+## Code standards
+
+PowerShell in this module follows the [PSModule Standards](https://psmodule.github.io/docs/Modules/Standards/) and the
+[MSXOrg Coding Standards](https://msxorg.github.io/docs/Coding-Standards/).
+
+## Questions
+
+Open a GitHub Discussion or file an issue if something is unclear.

docs/content/index.md

@@ -0,0 +1,37 @@
+# PowerShellGallery
+
+PowerShellGallery is a PowerShell module for interacting with the [PowerShell Gallery](https://www.powershellgallery.com).
+
+Version 1 focuses on two publisher-oriented workflows:
+
+- **Discovery** — read package and API metadata from the public OData v2 endpoint.
+- **Listing management** — list and unlist package versions you own, using gallery API credentials.
+
+## Installation
+
+Install the module from the PowerShell Gallery when a published release is available:
+
+```powershell
+Install-PSResource -Name PowerShellGallery -TrustRepository
+```
+
+## Quick start
+
+```powershell
+# Read gallery API metadata
+Get-PowerShellGalleryAPI
+
+# Search for packages
+Find-PowerShellGalleryPackage -Name 'Pester' -First 5
+
+# Get a specific package
+Get-PowerShellGalleryPackage -Name 'Pester' -Version '5.5.0'
+```
+
+## Documentation
+
+- [v1 Specification](specs/v1.md) — functional specification for the initial release.
+
+## Contributing
+
+See `CONTRIBUTING.md` and `AGENTS.md` in the repository root.