🚀 [Feature]: Decompose the Confluence client into the PSModule source layout

Implements the first working version of the module by porting the generalized Confluence REST v2 client and decomposing it into the PSModule one-function-per-file source layout.

- 35 public functions grouped by resource area (Auth, Config, API, Spaces, Site, Pages, BlogPosts, Folders, Comments, Labels, ContentProperties, Attachments, Restrictions, Users)

- 4 private helpers (Auth, Config); module state in variables/private

- Declares a dependency on the Context module via #Requires in header.ps1 (RequiredVersion 8.1.6), following the GitHub module pattern; credentials/config persist in the 'PSModule.Confluence' context vault

- Removes the template scaffold placeholders; adds Connecting/Pages examples and a credential-free surface test plus a skipped integration scaffold that reads connection details from environment secrets

- No tenant-specific data is included; examples use generic placeholders

Author: MariusStorhaug

README.md

@@ -1,15 +1,14 @@
 # Confluence
 
-A PowerShell module that interacts with Atlassian Confluence
+Confluence is a PowerShell module for interacting with the Atlassian Confluence Cloud REST API, both interactively and in automation.
 
-## Prerequisites
-
-This uses the following external resources:
-- The [PSModule framework](https://github.com/PSModule) for building, testing and publishing the module.
+It exposes pages, blog posts, folders, spaces, comments, labels, content properties, attachments, restrictions and more as PowerShell commands.
+Every command is a thin wrapper over a single generic REST entry point (`Invoke-ConfluenceRestMethod`). Credentials and module configuration
+are stored with the [Context](https://github.com/PSModule/Context) module, so you connect once and reuse the profile across sessions.
 
 ## Installation
 
-To install the module from the PowerShell Gallery, you can use the following command:
+Install the module from the PowerShell Gallery:
 
 ```powershell
 Install-PSResource -Name Confluence
@@ -18,52 +17,33 @@ Import-Module -Name Confluence
 
 ## Usage
 
-Here is a list of example that are typical use cases for the module.
-
-### Example 1: Greet an entity
-
-Provide examples for typical commands that a user would like to do with the module.
+Connect with a scoped Atlassian API token, then call the resource commands. The token is kept as a `SecureString` in the Context vault.
 
 ```powershell
-Greet-Entity -Name 'World'
-Hello, World!
+# Connect and store a reusable, named credential profile
+$token = Read-Host -AsSecureString   # a scoped Atlassian API token
+Connect-Confluence -ApiBaseUri 'https://api.atlassian.com/ex/confluence/<cloudId>' -Username 'you@example.com' -Token $token -SpaceKey 'DOCS'
+
+# Work with content
+$space = Get-ConfluenceSpace -Key 'DOCS'
+$page = New-ConfluencePage -SpaceId $space.id -Title 'Release notes' -Body '<p>Hello</p>'
+Set-ConfluencePage -PageId $page.id -Body '<p>Updated</p>'
+Get-ConfluencePageChild -PageId $page.id
 ```
 
-### Example 2
-
-Provide examples for typical commands that a user would like to do with the module.
-
-```powershell
-Import-Module -Name PSModuleTemplate
-```
-
-### Find more examples
-
-To find more examples of how to use the module, please refer to the [examples](examples) folder.
-
-Alternatively, you can use the Get-Command -Module 'This module' to find more commands that are available in the module.
-To find examples of each of the commands you can use Get-Help -Examples 'CommandName'.
+See the [examples](examples) folder for more, including managing contexts and pages.
 
 ## Documentation
 
-Link to further documentation if available, or describe where in the repository users can find more detailed documentation about
-the module's functions and features.
-
-## Contributing
-
-Coder or not, you can contribute to the project! We welcome all contributions.
-
-### For Users
+Documentation is published at [psmodule.io/Confluence](https://psmodule.io/Confluence/).
 
-If you don't code, you still sit on valuable information that can make this project even better. If you experience that the
-product does unexpected things, throw errors or is missing functionality, you can help by submitting bugs and feature requests.
-Please see the issues tab on this project and submit a new issue that matches your needs.
+Use PowerShell help and command discovery for module details:
 
-### For Developers
-
-If you do code, we'd love to have your contributions. Please read the [Contribution guidelines](CONTRIBUTING.md) for more information.
-You can either help by picking up an existing issue or submit a new one if you have an idea for a new feature or improvement.
+```powershell
+Get-Command -Module Confluence
+Get-Help New-ConfluencePage -Examples
+```
 
-## Acknowledgements
+## Contributing
 
-Here is a list of people and projects that helped this project in some way.
+Issues and pull requests are welcome. Please use the repository issue tracker to report bugs, request features, or discuss improvements.

examples/Connecting.ps1

@@ -0,0 +1,48 @@
+<#
+    .SYNOPSIS
+    Connect to Confluence and manage credential profiles (contexts).
+
+    .DESCRIPTION
+    Confluence stores each connection as a named context in the Context vault.
+    The token is kept as a SecureString. One context is the default; any command
+    can target a specific context with -Context.
+#>
+
+# Import the module
+Import-Module -Name 'Confluence'
+
+###
+### CONNECTING
+###
+
+# Connect with a scoped Atlassian API token and store a reusable default profile.
+$token = Read-Host -AsSecureString   # a scoped Atlassian API token
+Connect-Confluence -ApiBaseUri 'https://api.atlassian.com/ex/confluence/<cloudId>' -Username 'you@example.com' -Token $token -SpaceKey 'DOCS'
+
+# Store several sites/accounts under explicit names and select per call.
+Connect-Confluence -ApiBaseUri 'https://api.atlassian.com/ex/confluence/<cloudId>' -Username 'you@example.com' -Token $token -Name 'sandbox'
+Get-ConfluenceSpace -Key 'DOCS' -Context 'sandbox'
+
+###
+### CONTEXTS / PROFILES
+###
+
+# The default context
+Get-ConfluenceContext
+
+# All stored contexts
+Get-ConfluenceContext -ListAvailable
+
+###
+### MODULE CONFIGURATION
+###
+
+# Read and set module configuration (persisted in the same vault).
+Get-ConfluenceConfig
+Set-ConfluenceConfig -Name 'PerPage' -Value 50
+
+###
+### DISCONNECTING
+###
+
+Disconnect-Confluence -Name 'sandbox'

examples/General.ps1

@@ -0,0 +1,34 @@
+<#
+    .SYNOPSIS
+    Create, read, update and remove Confluence pages.
+
+    .DESCRIPTION
+    Assumes a default context is already connected (see Connecting.ps1).
+#>
+
+# Import the module
+Import-Module -Name 'Confluence'
+
+# Resolve the target space
+$space = Get-ConfluenceSpace -Key 'DOCS'
+
+# Create a page
+$page = New-ConfluencePage -SpaceId $space.id -Title 'Release notes' -Body '<p>First draft</p>'
+
+# Read it back (storage format by default)
+Get-ConfluencePage -PageId $page.id
+
+# Update the body (the version number is incremented automatically)
+Set-ConfluencePage -PageId $page.id -Body '<p>Updated content</p>'
+
+# Add a child page, then list children and descendants
+$child = New-ConfluencePage -SpaceId $space.id -Title 'Details' -ParentId $page.id -Body '<p>Nested</p>'
+Get-ConfluencePageChild -PageId $page.id
+Get-ConfluenceDescendant -PageId $page.id
+
+# Labels and comments
+Add-ConfluenceLabel -PageId $page.id -Label 'release', 'published'
+Add-ConfluenceComment -PageId $page.id -Body '<p>Looks good.</p>'
+
+# Remove the whole subtree (moves the pages to trash)
+Remove-ConfluencePage -PageId $page.id -Recurse

examples/Pages.ps1

@@ -0,0 +1,38 @@
+function Resolve-ConfluenceContext {
+    <#
+    .SYNOPSIS
+        Resolve a context argument into a usable credential-context object.
+    .DESCRIPTION
+        Accepts a context object/hashtable (returned as-is), a context name
+        (looked up in the vault), or nothing (falls back to the default context
+        recorded in the module configuration).
+    #>
+    [CmdletBinding()]
+    param(
+        # A context object, a context name, or $null for the default context.
+        [object]$Context
+    )
+
+    if ($null -ne $Context -and $Context -isnot [string]) {
+        return $Context
+    }
+
+    Initialize-ConfluenceConfig
+    $id = if ([string]::IsNullOrEmpty([string]$Context)) { $script:Confluence.Config['DefaultContext'] } else { [string]$Context }
+
+    if ([string]::IsNullOrEmpty($id)) {
+        throw 'No Confluence context was specified and no default context is set. Run Connect-Confluence first.'
+    }
+
+    $resolved = $null
+    try {
+        $resolved = Get-Context -ID $id -Vault $script:Confluence.ContextVault -ErrorAction Stop
+    } catch {
+        $resolved = $null
+    }
+
+    if (-not $resolved) {
+        throw "Confluence context '$id' was not found in vault '$($script:Confluence.ContextVault)'."
+    }
+    return $resolved
+}

src/finally.ps1

@@ -0,0 +1,21 @@
+function Resolve-ConfluenceToken {
+    <#
+    .SYNOPSIS
+        Return the plain-text API token from a SecureString or string.
+    .DESCRIPTION
+        The token is stored as a SecureString in the credential context; this
+        converts it to the plain text needed to build the Basic auth header.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        # The token as a SecureString or a plain string.
+        [Parameter(Mandatory)]
+        [object]$Token
+    )
+
+    if ($Token -is [System.Security.SecureString]) {
+        return [System.Net.NetworkCredential]::new('', $Token).Password
+    }
+    return [string]$Token
+}

src/functions/private/Auth/Resolve-ConfluenceContext.ps1

@@ -0,0 +1,28 @@
+function ConvertTo-ConfluenceHashtable {
+    <#
+    .SYNOPSIS
+        Convert a PSCustomObject (or hashtable) into a plain hashtable.
+    .DESCRIPTION
+        Used to turn the stored module-configuration context returned by
+        Get-Context into a mutable hashtable.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        # The object to convert.
+        [Parameter(Mandatory)]
+        [object]$InputObject
+    )
+
+    if ($InputObject -is [hashtable]) {
+        # Return a shallow clone so callers can mutate the result without altering
+        # the source hashtable (e.g. the built-in $script:Confluence.DefaultConfig).
+        return $InputObject.Clone()
+    }
+
+    $result = @{}
+    foreach ($property in $InputObject.PSObject.Properties) {
+        $result[$property.Name] = $property.Value
+    }
+    return $result
+}

src/functions/private/Auth/Resolve-ConfluenceToken.ps1

@@ -0,0 +1,45 @@
+function Initialize-ConfluenceConfig {
+    <#
+    .SYNOPSIS
+        Load the module configuration from the context vault into memory.
+    .DESCRIPTION
+        Loads the stored 'Module' configuration context, creating it from the
+        built-in defaults on first use. Missing default keys are backfilled.
+    #>
+    [CmdletBinding()]
+    param(
+        # Recreate the configuration from the built-in defaults.
+        [switch]$Force
+    )
+
+    if (-not $Force -and $null -ne $script:Confluence.Config) {
+        return
+    }
+
+    $vault = $script:Confluence.ContextVault
+    $id = $script:Confluence.DefaultConfig.ID
+
+    $stored = $null
+    if (-not $Force) {
+        try {
+            $stored = Get-Context -ID $id -Vault $vault -ErrorAction Stop
+        } catch {
+            $stored = $null
+        }
+    }
+
+    if ($Force -or -not $stored) {
+        $config = ConvertTo-ConfluenceHashtable -InputObject $script:Confluence.DefaultConfig
+    } else {
+        $config = ConvertTo-ConfluenceHashtable -InputObject $stored
+        foreach ($key in $script:Confluence.DefaultConfig.Keys) {
+            if (-not $config.ContainsKey($key)) {
+                $config[$key] = $script:Confluence.DefaultConfig[$key]
+            }
+        }
+    }
+
+    $config['ID'] = $id
+    $null = Set-Context -ID $id -Context $config -Vault $vault
+    $script:Confluence.Config = $config
+}