sagaz-ai 0.1.1 → 0.1.3

package/INSTALL.md

@@ -8,12 +8,41 @@
 - GitHub CLI (`gh`) installed and authenticated if you want GitHub Ops.
 - Access to the local Codex skills folder.
 
+## Platform Support
+
+Sagaz can be used on Windows and macOS through Codex Desktop. The npm installer uses the current user's home directory and installs the skill into the standard Codex skills folder:
+
+- Windows: `C:\Users\YOUR_USER\.codex\skills\sagaz`
+- macOS: `~/.codex/skills/sagaz`
+
+If your Codex Desktop installation uses a custom home folder, pass `--codex-home <path>`.
+
 ## Recommended: Install With npx
 
+### Windows PowerShell
+
 ```powershell
 npx sagaz-ai install
 ```
 
+Optional ecosystem copy:
+
+```powershell
+npx sagaz-ai install --ecosystem C:\Users\YOUR_USER\Documents\Sagaz\ai-orchestration-ecosystem
+```
+
+### macOS Terminal
+
+```bash
+npx sagaz-ai install
+```
+
+Optional ecosystem copy:
+
+```bash
+npx sagaz-ai install --ecosystem ~/Documents/Sagaz/ai-orchestration-ecosystem
+```
+
 Then open a new Codex Desktop thread and test:
 
 ```text
@@ -22,32 +51,52 @@ Sagaz: explain the available workflows.
 
 ## Optional Commands
 
+### Windows PowerShell
+
 ```powershell
 npx sagaz-ai status
 npx sagaz-ai doctor
 npx sagaz-ai install --force
 ```
 
-To also copy the ecosystem to a chosen folder:
+### macOS Terminal
 
-```powershell
-npx sagaz-ai install --ecosystem C:\Users\YOUR_USER\Documents\Sagaz\ai-orchestration-ecosystem
+```bash
+npx sagaz-ai status
+npx sagaz-ai doctor
+npx sagaz-ai install --force
 ```
 
 ## Manual Install
 
-Copy:
+Copy the Sagaz skill folder from the repository.
+
+Windows source folder:
 
 ```text
 codex-skill\sagaz
 ```
 
-into:
+macOS source folder:
+
+```text
+codex-skill/sagaz
+```
+
+into the platform-specific Codex skill folder.
+
+Windows:
 
 ```text
 C:\Users\YOUR_USER\.codex\skills\sagaz
 ```
 
+macOS:
+
+```text
+~/.codex/skills/sagaz
+```
+
 Then open a new Codex Desktop thread and test:
 
 ```text
@@ -64,6 +113,8 @@ Sagaz: use the appropriate workflow for this project. Maintain run state, handof
 
 ## GitHub Ops
 
+### Windows PowerShell
+
 Authenticate GitHub CLI:
 
 ```powershell
@@ -75,4 +126,26 @@ Verify:
 ```powershell
 gh auth status
 git --version
-```
+```
+
+### macOS Terminal
+
+Install Git and GitHub CLI if needed:
+
+```bash
+xcode-select --install
+brew install gh
+```
+
+Authenticate GitHub CLI:
+
+```bash
+gh auth login -h github.com
+```
+
+Verify:
+
+```bash
+gh auth status
+git --version
+```

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
 
@@ -77,14 +78,17 @@ Key areas:
 
 ### Recommended: Install With npx
 
-```powershell
-npx sagaz-ai install
-```
+Sagaz supports Windows and macOS through Codex Desktop. The npm installer installs the skill into the current user's Codex skills folder:
 
-Then open a new Codex Desktop thread and run:
+- Windows: `C:\Users\YOUR_USER\.codex\skills\sagaz`
+- macOS: `~/.codex/skills/sagaz`
 
-```text
-Sagaz: explain the available workflows.
+If your Codex Desktop installation uses a custom home folder, pass `--codex-home <path>`.
+
+#### Windows PowerShell
+
+```powershell
+npx sagaz-ai install
 ```
 
 Optional: also copy the ecosystem to a known local folder:
@@ -100,36 +104,79 @@ npx sagaz-ai status
 npx sagaz-ai doctor
 ```
 
+#### macOS Terminal
+
+```bash
+npx sagaz-ai install
+```
+
+Optional: also copy the ecosystem to a known local folder:
+
+```bash
+npx sagaz-ai install --ecosystem ~/Documents/Sagaz/ai-orchestration-ecosystem
+```
+
+Check installation:
+
+```bash
+npx sagaz-ai status
+npx sagaz-ai doctor
+```
+
+Then open a new Codex Desktop thread and run:
+
+```text
+Sagaz: explain the available workflows.
+```
+
 ### Manual Installation
 
 #### 1. Clone Or Download The Repository
 
+Windows PowerShell:
+
 ```powershell
 git clone https://github.com/tscabral1/sagaz.git
 ```
 
+macOS Terminal:
+
+```bash
+git clone https://github.com/tscabral1/sagaz.git
+```
+
 Or download the ZIP from GitHub.
 
 #### 2. Copy The Skill Into Codex
 
-On Windows, the local Codex skills folder is usually:
+Copy the Sagaz skill folder from the repository.
+
+Windows source folder:
 
 ```text
-C:\Users\YOUR_USER\.codex\skills
+codex-skill\sagaz
 ```
 
-Copy this folder:
+macOS source folder:
 
 ```text
-codex-skill\sagaz
+codex-skill/sagaz
 ```
 
-into:
+into the platform-specific Codex skills folder.
+
+Windows:
 
 ```text
 C:\Users\YOUR_USER\.codex\skills\sagaz
 ```
 
+macOS:
+
+```text
+~/.codex/skills/sagaz
+```
+
 #### 3. Keep The Ecosystem Available
 
 Keep `ai-orchestration-ecosystem/` accessible in the Codex workspace or in a known local folder.
@@ -160,6 +207,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/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/bin/sagaz.js

@@ -23,9 +23,16 @@ Usage:
   npx sagaz-ai doctor
 
 Options:
-  --codex-home <path>     Override Codex home. Default: ~/.codex
+  --codex-home <path>     Override Codex home. Default: ~/.codex on Windows, macOS, and Linux
   --ecosystem <path>      Also copy ai-orchestration-ecosystem to a target folder
   --force                 Overwrite existing installed skill
+
+Examples:
+  Windows:
+    npx sagaz-ai install --ecosystem C:\\Users\\YOUR_USER\\Documents\\Sagaz\\ai-orchestration-ecosystem
+
+  macOS:
+    npx sagaz-ai install --ecosystem ~/Documents/Sagaz/ai-orchestration-ecosystem
 `);
 }
 

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.1",
+  "version": "0.1.3",
   "description": "Sagaz AI orchestration ecosystem installer for Codex Desktop.",
   "type": "module",
   "bin": {