docs: update release policy for new CI/CD architecture

- Document separate semantic-release and publish workflows
- Explain automatic publishing for stable releases (v[0-9]+.[0-9]+.[0-9]+)
- Document manual publishing via workflow_dispatch
- Add workflow execution flow diagrams
- Document key design decisions and rationale
- Update contributor guidance for new release process
- Remove outdated local versioning commands
- Clarify that dev releases are available from GitHub releases

docs: update release-policy

Update the release policy documentation example to reflect the actual
current state of the project:
- Package name: hatch-xclam (was: hatch)
- Description: Package manager for the Cracking Shells ecosystem
- Dependencies: Updated to match current pyproject.toml

Update the version information to be a pattern: MAJOR.MINOR.PATCH[-dev.N] (was: 0.4.2)

This ensures the documentation accurately represents the project's
release configuration and versioning strategy.

Author: LittleCoinCoin

docs/articles/devs/contribution_guides/release_policy.md

@@ -30,16 +30,20 @@ The project maintains version information in the primary Python package configur
 - No separate `VERSION.meta` or `VERSION` files are used
 - Version is automatically updated by semantic-release based on conventional commits
 
-Example from `Hatch/pyproject.toml`:
+Example from `pyproject.toml`:
 
 ```toml
 [project]
-name = "hatch"
-version = "0.4.2"
-description = "Package manager for Model Context Protocol servers"
+name = "hatch-xclam"
+version = "MAJOR.MINOR.PATCH[-dev.N]"
+description = "Package manager for the Cracking Shells ecosystem"
 dependencies = [
-    "hatch-validator>=0.1.0",
-    "requests>=2.28.0",
+    "jsonschema>=4.0.0",
+    "requests>=2.25.0",
+    "packaging>=20.0",
+    "docker>=7.1.0",
+    "pydantic>=2.0.0",
+    "hatch-validator>=0.8.0"
 ]
 ```
 
@@ -88,41 +92,63 @@ The release automation is configured in `.releaserc.json` using:
 
 ## Publishing to PyPI
 
-When a release is created:
-1. **Build artifacts** are generated by the semantic-release process
-2. **Package is published** to PyPI when the release workflow is enhanced
-3. **Dev versions** published on `dev` branch will be pre-releases
-4. **Production versions** published on `main` branch will be stable releases
-
-### Enhancement Status
-- ✅ **PyPI publishing workflow**: Added to `.github/workflows/semantic-release.yml`
-- ✅ **Trusted publishing**: Configured with GitHub environment 
-- ✅ **Artifact handling**: Dist files built and uploaded before publishing
-
-## How to run and test locally
-
-Quick commands you can run from the repository root (PowerShell examples):
-
-```powershell
-# Print current computed version
-python versioning/version_manager.py --get
-
-# Update version for a given branch (this writes both files)
-python versioning/version_manager.py --update-for-branch dev
-
-# Increment a patch locally (writes both files)
-python versioning/version_manager.py --increment patch --branch dev
-
-# Prepare simple VERSION file for a build (convert from VERSION.meta)
-python versioning/prepare_version.py
-```
-
-Notes:
-
-- After running local updates, commit the updated `VERSION` and `VERSION.meta` if you intend to push the change.
-- Prefer letting CI run `--update-for-branch` and perform the commit/tag steps automatically unless you need to perform an explicit offline bump.
-
-## Tag cleanup and maintenance
+The publishing workflow is separate from the release workflow to ensure clean separation of concerns:
+
+### Automatic Publishing (Stable Releases)
+When a stable release tag is created (matching pattern `v[0-9]+.[0-9]+.[0-9]+`):
+1. **Tag push triggers** `.github/workflows/publish.yml`
+2. **Code is tested** to ensure tag points to valid code
+3. **Package is built** using `python -m build`
+4. **Package is published** to PyPI using trusted publishing (OIDC)
+
+Only stable releases are automatically published to PyPI. Development releases (`v0.7.0-dev.X`) are available from GitHub releases.
+
+### Manual Publishing (On-Demand)
+For special cases, you can manually publish any tag using workflow dispatch:
+
+1. Go to GitHub Actions → "Publish to PyPI" workflow
+2. Click "Run workflow"
+3. Provide inputs:
+   - **tag**: Git tag to publish (e.g., `v1.0.0`)
+   - **ref**: Optional branch/commit (defaults to `main`)
+4. Workflow runs and publishes to PyPI
+
+### Workflow Architecture
+- **`.github/workflows/semantic-release.yml`**: Handles testing and automated version bumping on branch pushes
+- **`.github/workflows/publish.yml`**: Handles PyPI publication on stable release tags or manual dispatch
+
+### Publishing Status
+- ✅ **Automatic publishing**: Configured for stable releases (v[0-9]+.[0-9]+.[0-9]+)
+- ✅ **Manual publishing**: Available via workflow_dispatch
+- ✅ **Trusted publishing**: Configured with GitHub OIDC environment
+- ✅ **Idempotent**: Uses `skip-existing: true` to handle retries gracefully
+
+## For Contributors
+
+### Creating a Release
+1. Use conventional commits in your pull requests
+2. When ready to release, merge to `main` or `dev`
+3. Semantic-release automatically:
+   - Analyzes commits
+   - Calculates version
+   - Updates `pyproject.toml`
+   - Generates changelog
+   - Creates git tag
+   - Creates GitHub release
+4. Tag creation automatically triggers PyPI publishing (for stable releases)
+
+### Manual Publishing
+If you need to publish a specific tag manually:
+1. Go to GitHub Actions → "Publish to PyPI"
+2. Click "Run workflow"
+3. Enter the tag name (e.g., `v1.0.0`)
+4. Optionally specify a branch/commit
+5. Workflow publishes to PyPI
+
+### Version Information
+- Current version is always in `pyproject.toml` under `[project]` section
+- Do not manually edit version files - let semantic-release handle it
+- Version follows semantic versioning: `MAJOR.MINOR.PATCH`
 
 ## Release Commit Examples
 
@@ -147,10 +173,48 @@ BREAKING CHANGE: Updated package schema version
 - ✓ **Conventional commits**: Enforced with commitlint
 - ✓ **Version management**: Automated via `@artessan-devs/sr-uv-plugin`
 - ✓ **Changelog generation**: Automated
-- ✓ **GitHub releases**: Automated  
-- ⚠ **PyPI publishing**: Needs workflow enhancement
+- ✓ **GitHub releases**: Automated
+- ✓ **PyPI publishing**: Fully automated for stable releases
+- ✓ **Manual publishing**: Available via workflow_dispatch
+
+## Workflow Execution Flow
+
+### Development Workflow (Push to `dev` or `main`)
+```
+Developer push → semantic-release.yml
+  ├─ test job: Validates code
+  └─ release job: Creates version bump, changelog, and tag
+       └─ Tag creation triggers publish.yml
+```
+
+### Publishing Workflow (Tag creation)
+```
+Tag push (v[0-9]+.[0-9]+.[0-9]+) → publish.yml
+  ├─ test job: Validates tag points to valid code
+  └─ publish-pypi job: Builds and publishes to PyPI
+```
+
+### Manual Publishing
+```
+Workflow dispatch → publish.yml
+  ├─ Accepts tag and optional ref inputs
+  ├─ test job: Validates code
+  └─ publish-pypi job: Builds and publishes to PyPI
+```
+
+## Key Design Decisions
+
+1. **Separate Workflows**: Release creation and publishing are independent workflows
+   - Prevents double-execution issues
+   - Allows manual publishing without re-running release logic
+   - Uses git-native tag triggers instead of text matching
+
+2. **Stable Release Only**: Only tags matching `v[0-9]+.[0-9]+.[0-9]+` are auto-published
+   - Development releases available from GitHub releases
+   - Reduces PyPI clutter
+   - Allows manual publishing of dev versions if needed
 
-## Action Items for v0.7.0 Release
-1. ✅ Documentation updates (this task)
-2. ⚠ Add PyPI publishing workflow 
-3. ✅ Ensure all contributors understand conventional commit format
+3. **Idempotent Publishing**: `skip-existing: true` configuration
+   - Handles workflow retries gracefully
+   - Prevents failures on duplicate versions
+   - Safe to re-run without side effects