⚙️ [Maintenance]: Split module archetypes guidance (#66)

Module archetype guidance now documents Integration and Data modules
with flexible transport and Context patterns. The guidance clarifies
design choices for exposing or hiding transport abstractions, Context
functions for targeting environments, and the ConvertFrom/ConvertTo data
flow directions.

## New: Module archetype guidance

PSModule modules fall into two standardized archetypes. The new
Module-Types.md page documents:

- **Integration (API) modules**: Wrap external services via REST or
GraphQL. Commands map to resources and intents, not HTTP methods.
Transport abstractions (REST/GraphQL functions) may be private, public,
or combined with public Context depending on audience needs.
- **Data modules**: Convert between data format representations and
PowerShell objects. Conversion always flows through PSCustomObject as
the neutral pivot, with ConvertFrom and ConvertTo functions moving
bidirectionally.

## Changed: Transport abstraction is flexible, not prescriptive

Transport, REST methods, and GraphQL functions do not have to be
private. Modules now document three strategies:

- **Private transport** (common): Keep REST/GraphQL helpers private.
Public functions accept resolved inputs and typed objects. Follows
Dependency Inversion at the network boundary.
- **Public transport**: Expose REST or GraphQL functions for power users
or module composition.
- **Public Context**: Expose Context functions so users can configure
and target specific contexts and environments directly.

Module authors choose the strategy that best serves their audience.

## Changed: Context modules must expose functions and object types

The Context module provides on-disk storage for user data and secrets
organized by context and environment. Modules must expose functions and
object types so users can programmatically target specific contexts and
environments. Users need to select which environment or context their
functions operate against.

## Improved: ConvertFrom/ConvertTo data flow clarity

The verb vocabulary table now explicitly shows data flow directions:

- **ConvertFrom-<Format>**: Format-specific input → PSCustomObject
- **ConvertTo-<Format>**: PSCustomObject → Format-specific output

## Technical Details

- Added `src/docs/Modules/Module-Types.md` with Integration and Data
archetype guidance.
- Updated `src/docs/Modules/index.md` with module section links.
- Added cross-link from Repository-Defaults.md to module types.
- Updated site navigation in `src/zensical.toml`.
- Split from PR #61 to isolate module archetype guidance from README
policy and onboarding defaults.

Author: MariusStorhaug

src/docs/Modules/Module-Types.md

@@ -0,0 +1,106 @@
+# Module types
+
+Most PSModule modules fall into one of a few archetypes. The general rules in
+[PowerShell module standard](Standards.md) and [PowerShell Standards](../PowerShell/Standard/index.md) always apply; this
+page adds the conventions that are specific to a module's type so that modules of the same kind feel
+the same to use.
+
+Two archetypes have enough shared shape to standardize:
+
+- **Integration (API) modules** wrap an external service's REST or GraphQL API.
+- **Data modules** convert or manage a data format or in-memory structure.
+
+A module can be both (for example, an integration module that also exposes conversion helpers).
+Apply each relevant section.
+
+## Integration (API) modules
+
+Integration modules are the PowerShell face of an external service. `GitHub`, and the
+service-client modules such as `Anthropic`, `OpenAI`, `Bluesky`, and `Domeneshop`, are integration
+modules.
+
+### Command naming maps to the resource, not the HTTP method
+
+Name commands after the resource and the intent, using approved verbs. Never name a command after
+the HTTP method or the endpoint path. Map REST methods to verbs:
+
+| REST method | PowerShell verb | Example |
+| ----------- | --------------- | ------- |
+| `GET` | `Get-` | `Get-GitHubRepository` |
+| `POST` (create) | `New-` / `Add-` | `New-GitHubRepository` |
+| `PUT` / `PATCH` (update) | `Set-` / `Update-` | `Set-GitHubRepository` |
+| `DELETE` | `Remove-` | `Remove-GitHubRepository` |
+| Non-CRUD action | Approved verb for the intent | `Invoke-`, `Start-`, `Stop-`, `Enable-`, ... |
+
+Prefix the noun with the service's term of art (`GitHubRepository`, not `Repository`).
+
+### Transport abstraction
+
+Lower-level helpers own the concrete `Invoke-RestMethod` / GraphQL / HTTP calls. How you expose
+or hide this abstraction is a design choice:
+
+- **Private transport** (common): Keep REST, GraphQL, and HTTP helpers private. Public functions
+  accept resolved inputs and typed objects. This follows the Dependency Inversion rule from
+  [Standards](Standards.md#solid-applied) applied to the network boundary.
+- **Public transport**: Expose REST or GraphQL functions publicly for power users or module
+  composition.
+- **Public Context**: Expose the `Context` module as public so users can configure and manage
+  module state, secrets, and settings directly.
+
+Choose the strategy that best serves your module's audience.
+
+### Use Context for user and module settings
+
+Integration modules persist state with the [`Context`](https://github.com/PSModule/Context) module
+rather than inventing bespoke storage. Context provides on-disk storage for user data and secrets,
+organized by context and environment. Two kinds of state are both standard:
+
+- **User settings and secrets**: accounts, tokens, sessions, and per-user configuration. Store these
+  in a per-user context. `Context` encrypts secrets at rest (via `Sodium`), so a user can resume work
+  without reconfiguring or logging in again when the service supports session refresh.
+- **Module settings**: module-wide defaults, endpoints, and feature flags that are not tied to a
+  single user. Store these in a module-scoped context.
+
+Your module must expose functions and object types so users can target specific contexts and
+environments. Users need to be able to read from, write to, and manage contexts programmatically,
+selecting which environment or context their functions operate against. Persisting both through
+`Context` gives every integration module the same, discoverable settings model and keeps secrets
+out of source, logs, and plain files.
+
+## Data modules
+
+Data modules convert between representations or manage an in-memory structure. `Hashtable` is the
+reference shape; `Base64`, `Json`, `Lua`, `Hcl`, `Sodium`, and `Uri` follow the same pattern.
+
+### The neutral object is the pivot
+
+Every conversion goes through the neutral PowerShell object model
+(`[PSCustomObject]` / `[hashtable]` / `[PSObject]`). `ConvertFrom-<Format>` parses a
+format-specific representation into an object; `ConvertTo-<Format>` renders an object into the
+format. Converting through the object as a common pivot means any format interoperates with any
+other, instead of writing a direct converter for every pair.
+
+Always ship both directions so data can round-trip between the format and the object model.
+
+### Verb vocabulary
+
+| Verb pattern | Purpose |
+| ------------ | ------- |
+| `ConvertFrom-<Format>` | Format-specific text/representation → `[PSCustomObject]` / `[hashtable]` |
+| `ConvertTo-<Format>` | `[PSCustomObject]` / `[hashtable]` → format-specific text/representation |
+| `Import-<Noun>` | Read from a file or store into objects |
+| `Export-<Noun>` | Write objects to a file or store |
+| `Format-<Noun>` | Produce a normalized or pretty rendering |
+| `Merge-<Noun>` | Combine two structures |
+| `Compare-<Noun>` | Diff two structures |
+| `Test-<Noun>` | Validate a value or structure |
+| `Remove-<Noun>Entry` | Remove elements by criteria |
+
+The `Hashtable` module demonstrates the full set: `ConvertFrom-Hashtable`, `ConvertTo-Hashtable`,
+`Import-Hashtable`, `Export-Hashtable`, `Format-Hashtable`, `Merge-Hashtable`, and
+`Remove-HashtableEntry`.
+
+## Where this connects
+
+- [PowerShell module standard](Standards.md): layout, private functions, and the mandatory context parameter.
+- [Repository Defaults](Repository-Defaults.md): repository files, README shape, and agent onboarding.

src/docs/Modules/Repository-Defaults.md

@@ -2,7 +2,7 @@
 
 This page defines the default repository contract for PowerShell module repositories in the PSModule organization. It describes what a newly created or maintained module repository should look like before module-specific code, tests, documentation, and managed repository files are considered.
 
-The implementation standard still lives in [PowerShell module standard](Standards.md). This page covers repository defaults: files, metadata, README shape, release integration, placeholder handling, shared community files, and managed-file distribution.
+The implementation standard still lives in [PowerShell module standard](Standards.md). Type-specific conventions for integration (API) and data modules live in [Module types](Module-Types.md). This page covers repository defaults: files, metadata, README shape, release integration, placeholder handling, shared community files, and managed-file distribution.
 
 ## Scope
 

src/docs/Modules/index.md

@@ -13,6 +13,7 @@ This section is the local source of truth for:
 
 - [Repository Defaults](Repository-Defaults.md)
 - [Standards](Standards.md)
+- [Module types](Module-Types.md)
 - [Test Specification](Test-Specification.md)
 - [Versioning](Versioning.md)
 - [Catalog](Catalog/index.md)

src/zensical.toml

@@ -21,6 +21,7 @@ nav = [
     "Modules/index.md",
     {"Repository Defaults" = "Modules/Repository-Defaults.md"},
     {"Standards" = "Modules/Standards.md"},
+    {"Module types" = "Modules/Module-Types.md"},
     {"Test Specification" = "Modules/Test-Specification.md"},
     {"Versioning" = "Modules/Versioning.md"},
     {"Catalog" = [