Auto-sync .kiro/ from master (post-checkout hook)

.kiro/steering/versioning.md

@@ -0,0 +1,83 @@
+# Versioning & Release Management
+
+## Version Numbering
+
+This project uses **Semantic Versioning** (MAJOR.MINOR.PATCH) but with a practical cadence-based approach to avoid runaway patch numbers.
+
+### When to bump what
+
+| Change type | Bump | Example |
+|---|---|---|
+| Breaking change (new DB engine, incompatible API/config, data migration required) | MAJOR | 2.0.0 → 3.0.0 |
+| New feature, new page, new integration, significant enhancement | MINOR | 2.1.0 → 2.2.0 |
+| Bug fix, UI tweak, docs update, refactor with no user-visible change | PATCH | 2.1.0 → 2.1.1 |
+
+### Cadence rules to keep numbers sane
+
+- **Bundle bug fixes into the next minor release** rather than tagging a patch for every individual fix. Only cut a standalone patch release (x.y.Z) if a fix is urgent and needs to ship before the next feature is ready.
+- **One minor bump per feature batch** — if a work session produces 2–3 features and 5 bug fixes, that's one minor release, not five patches and two minors.
+- **Tag releases at logical milestones**, not per-commit. A good release boundary is: "a user would notice something new or different."
+- **Never exceed x.y.5 in patches** before rolling into the next minor. If you're at x.y.5 and still shipping fixes, just bump to x.(y+1).0 and include the fixes there.
+
+### Practical workflow
+
+1. Work on features and fixes on `master` as normal — no version bump per commit.
+2. When a logical batch is complete (end of a sprint, feature area done, before a deploy you want to mark), decide the version:
+   - Any breaking change since last tag? → MAJOR
+   - Any new features? → MINOR
+   - Only fixes? → PATCH (but prefer bundling into next MINOR)
+3. Update `CHANGELOG.md` with the new version section.
+4. Commit the changelog update.
+5. Tag and push:
+   ```bash
+   git tag -a vX.Y.Z -m "vX.Y.Z — short summary"
+   git push origin vX.Y.Z
+   git push backup vX.Y.Z
+   ```
+6. Create a GitLab Release from the tag (renders changelog on the Releases page):
+   ```bash
+   # Extract the changelog section for this version from CHANGELOG.md
+   # Then create the release via GitLab API:
+   curl --silent --request POST \
+     --header "PRIVATE-TOKEN: $GITLAB_PAT" \
+     --header "Content-Type: application/json" \
+     --data "{
+       \"tag_name\": \"vX.Y.Z\",
+       \"name\": \"vX.Y.Z\",
+       \"description\": \"<changelog section in markdown>\"
+     }" \
+     "https://vulcan.apophisnetworking.net/api/v4/projects/jramos%2Fcve-dashboard/releases"
+   ```
+
+### GitLab Release creation details
+
+- The GitLab instance is `https://vulcan.apophisnetworking.net`
+- Project path: `jramos/cve-dashboard` (URL-encoded: `jramos%2Fcve-dashboard`)
+- Auth: `GITLAB_PAT` from `backend/.env`
+- The `description` field accepts full markdown — paste the relevant `## [vX.Y.Z]` section from `CHANGELOG.md`
+- The release appears under **Deployments → Releases** in the GitLab sidebar with rendered markdown, download archives, and a badge showing the latest version
+
+### What counts as a "breaking change"
+
+- Database engine or schema change that requires migration with data transformation
+- Removal or rename of API endpoints that external consumers depend on
+- Environment variable changes that would break an existing deployment on pull
+- Dropping support for a previously supported platform or runtime version
+
+Adding new required env vars for *new* features is NOT breaking — existing features still work without them.
+
+## Release Suggestion Prompt
+
+After completing work (features, fixes, or both), suggest the next version number based on:
+
+1. What the last tagged version is (`git tag -l --sort=-v:refname | head -1`)
+2. What changed since that tag (`git log <last_tag>..HEAD --oneline`)
+3. The cadence rules above
+
+Format the suggestion as:
+
+> **Suggested release:** vX.Y.Z
+> **Reason:** [brief justification based on change types]
+> **Changelog entries to add:** [bullet list of items to add]
+
+Only suggest a release if there are meaningful user-visible changes. Internal refactors, test additions, and CI tweaks alone do not warrant a release.