sagaz-ai 0.1.2 → 0.1.4

package/INSTALL.md

@@ -3,7 +3,8 @@
 ## Requirements
 
 - Codex Desktop.
-- Node.js 18+ if installing with `npx`.
+- Node.js 22.14+ if installing with `npx`.
+- Node.js 24 LTS is preferred for new installations.
 - Git installed.
 - GitHub CLI (`gh`) installed and authenticated if you want GitHub Ops.
 - Access to the local Codex skills folder.
@@ -17,6 +18,21 @@ Sagaz can be used on Windows and macOS through Codex Desktop. The npm installer
 
 If your Codex Desktop installation uses a custom home folder, pass `--codex-home <path>`.
 
+## Node.js And npm
+
+Use a currently supported Node.js release:
+
+- Recommended minimum: Node.js 22.14+.
+- Preferred for new installations: Node.js 24 LTS.
+- Avoid Node.js 18 and Node.js 20 for new Sagaz installations because they are no longer the best compatibility baseline for current npm publishing and GitHub Actions behavior.
+
+Verify:
+
+```bash
+node --version
+npm --version
+```
+
 ## Recommended: Install With npx
 
 ### Windows PowerShell

package/README.md

@@ -41,6 +41,7 @@ Sagaz also guides the user through the process. At the end of each phase, it exp
 - **Tool registry:** Sagaz verifies and recommends tools such as GitHub CLI, Playwright, Vercel, Expo/EAS, Supabase, Firebase, Stripe, CI/CD, and observability services.
 - **Stack presets:** common web, mobile, backend, database, and dashboard stacks are documented as starting points.
 - **Sagaz evaluations:** scenario-based checks help prevent regressions in the orchestration system itself.
+- **Compatibility audits:** Sagaz can check whether Windows, macOS, npm, Node.js, Codex Desktop, AI model behavior, GitHub, package contents, or external platform changes require a Sagaz update.
 
 ## How It Works
 
@@ -84,6 +85,8 @@ Sagaz supports Windows and macOS through Codex Desktop. The npm installer instal
 
 If your Codex Desktop installation uses a custom home folder, pass `--codex-home <path>`.
 
+Use Node.js 22.14+ with npm for installation. Node.js 24 LTS is preferred for new installations because it aligns with current npm publishing and GitHub Actions compatibility. Avoid Node.js 18 and Node.js 20 for new Sagaz installations.
+
 #### Windows PowerShell
 
 ```powershell
@@ -206,6 +209,8 @@ For tool-heavy work, Sagaz uses a tool registry to verify local availability and
 
 For common project types, Sagaz can start from documented stack presets such as Next.js on Vercel, React with Vite, Expo mobile, React Native, Supabase, Firebase, Node APIs, static sites, and admin dashboards.
 
+When asked whether Sagaz needs updates, Sagaz should run a compatibility update audit across Windows, macOS, npm, Node.js, Codex Desktop, current model/tool behavior, GitHub, local installed skill, package contents, documentation, CI/CD, and relevant external platforms before recommending a new version.
+
 ## Web Example
 
 ```text

package/ai-orchestration-ecosystem/INDEX.md

@@ -60,6 +60,7 @@ See `protocols/` for quality gates, testing matrix, stack selection, design qual
 - `protocols/ai-application-quality.md`
 - `protocols/agent-observability.md`
 - `protocols/durable-run-state.md`
+- `protocols/compatibility-update-audit.md`
 
 ## Tools
 

package/ai-orchestration-ecosystem/governance/ecosystem-maintenance.md

@@ -10,4 +10,7 @@ Maintain Sagaz as a reliable, safe, versionable, low-token orchestration ecosyst
 - Does it reduce future risk?
 - Does it preserve low token usage?
 - Is the user impact clear?
+- If the user asks whether Sagaz needs updates, apply `protocols/compatibility-update-audit.md` before answering.
+- Check Windows, macOS, npm, Node.js, Codex Desktop, AI model behavior, GitHub, package contents, local installed skill, documentation, CI/CD, and relevant external platform assumptions.
+- If a compatibility risk is found, explain it and ask whether the user wants Sagaz updated and released.
 

package/ai-orchestration-ecosystem/governance/package-release-policy.md

@@ -40,8 +40,11 @@ The repository should include:
 
 - package checks on push and pull request
 - manual npm publishing workflow
+- GitHub Actions configured with Node.js 24 unless a newer supported LTS baseline is intentionally adopted
 
-The npm publishing workflow requires an `NPM_TOKEN` repository secret. Do not assume it exists. If it is missing, guide the user through creating it and explain why it is needed.
+The npm publishing workflow requires either trusted publishing or an `NPM_TOKEN` repository secret. Do not assume either is configured. If missing, guide the user through the safest available option and explain why it is needed.
+
+Use Node.js 22.14+ as the minimum package baseline and Node.js 24 LTS for GitHub Actions unless a compatibility audit recommends a newer baseline.
 
 ## npm Publishing
 

package/ai-orchestration-ecosystem/protocols/compatibility-update-audit.md

@@ -0,0 +1,86 @@
+# Compatibility Update Audit
+
+## Purpose
+
+Detect whether Sagaz needs an update because the surrounding ecosystem changed. Use this protocol whenever the user asks if Sagaz needs updates, whether everything is current, whether a new Codex/model release affects Sagaz, or whether Sagaz is still safe to use.
+
+## Mandatory Scope
+
+Check every relevant variable before answering:
+
+- Windows installation behavior
+- macOS installation behavior
+- Codex Desktop skill discovery and local skill folder behavior
+- current AI model behavior, tool behavior, and instruction-following assumptions
+- npm package version and `latest` tag
+- Node.js supported versions and npm CLI behavior
+- Git and GitHub CLI availability expectations
+- GitHub repository state, workflows, permissions, and release process
+- package contents included by `npm pack`
+- installer behavior through `npx sagaz-ai@latest`
+- Markdown ecosystem structure
+- local installed skill versus repository skill
+- documentation consistency across README, INSTALL, skill, and governance files
+- CI/CD workflow compatibility
+- browser, Playwright, deployment, mobile, and tool registry assumptions when relevant
+- breaking changes in platforms Sagaz recommends, such as Vercel, Expo/EAS, Supabase, Firebase, Stripe, OpenAI, OpenRouter, TogetherAI, Groq, and GitHub Actions
+
+## Information Sources
+
+Use local checks first:
+
+- repository files
+- installed skill files
+- `git status`
+- `npm test`
+- `npm pack --dry-run`
+- `npm view sagaz-ai version`
+- `node --version`
+- `npm --version`
+- `git --version`
+- `gh --version`
+- `gh auth status`
+
+Use web or official documentation when the question depends on current external behavior, including Codex Desktop, OpenAI models, npm, Node.js, GitHub Actions, GitHub CLI, or platform APIs. Prefer official sources.
+
+## Audit Output
+
+Answer with:
+
+```md
+Current Sagaz version:
+Local repository state:
+npm latest:
+Installed local skill:
+Windows status:
+macOS status:
+Node/npm status:
+Codex Desktop/model risk:
+GitHub/GitHub CLI status:
+External platform risks:
+Documentation status:
+Package status:
+Conclusion:
+Recommended Sagaz update:
+Needs user permission:
+```
+
+## Update Decision
+
+Recommend a Sagaz update when:
+
+- a platform behavior changed and may break installation or usage
+- documentation is wrong, incomplete, or ambiguous
+- npm/package behavior changed
+- Codex Desktop skill behavior changed
+- model/tool behavior requires new operating rules
+- a dependency or recommended platform introduced a breaking change
+- local installed skill is behind repository or npm
+- package contents do not match the repository expectations
+- verification cannot be completed without a new check or script
+
+Do not recommend a new release only because a dependency has a newer version. Recommend a release only when Sagaz behavior, safety, installation, documentation, or verification needs to change.
+
+## Permission Rule
+
+If an update is recommended, explain the reason, impact, risk, and proposed version bump. Ask the user for permission before editing files, committing, pushing, publishing, creating releases, changing secrets, or updating installed tools.

package/codex-skill/sagaz/SKILL.md

@@ -32,7 +32,8 @@ If navigation is needed, read:
 11. For multi-phase or production work, apply durable run state and compact agent observability.
 12. Use the tool registry before recommending or using external tools, connectors, deployments, publishing, or account-linked actions.
 13. Use stack presets as starting points when recommending technologies, then adapt to user constraints.
-14. Do not declare done without verification evidence proportional to risk.
+14. When the user asks whether Sagaz needs updates, apply the compatibility update audit across Windows, macOS, npm, Node.js, Codex Desktop, AI model behavior, GitHub, package contents, installed skill, and relevant external platforms before recommending a new version.
+15. Do not declare done without verification evidence proportional to risk.
 
 ## Quick Selection
 
@@ -46,6 +47,7 @@ If navigation is needed, read:
 - Tools/connectors: `tools/tool-registry.md`
 - Stack presets: `stack-presets/`
 - Sagaz quality checks: `evals/sagaz-evaluation-suite.md`
+- Sagaz update checks: `protocols/compatibility-update-audit.md`
 
 ## Required Handoff
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sagaz-ai",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Sagaz AI orchestration ecosystem installer for Codex Desktop.",
   "type": "module",
   "bin": {
@@ -29,7 +29,7 @@
   "author": "Thiago Cabral",
   "license": "MIT",
   "engines": {
-    "node": ">=18"
+    "node": ">=22.14"
   },
   "repository": {
     "type": "git",