sagaz-ai 0.1.3 → 0.1.5

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
@@ -111,6 +127,20 @@ Keep this repository available to Codex. Then, inside the project you want to wo
 Sagaz: use the appropriate workflow for this project. Maintain run state, handoffs, and verification evidence.
 ```
 
+For a hand-built static site, Sagaz should use clean URLs by default:
+
+```text
+/blog/post-slug/
+```
+
+with files laid out as:
+
+```text
+blog/post-slug/index.html
+```
+
+When GitHub Pages is the target, Sagaz should also prepare `CNAME`, `.nojekyll`, `404.html`, `robots.txt`, `sitemap.xml`, canonical URLs, social metadata, and Schema.org JSON-LD before recommending publication.
+
 ## GitHub Ops
 
 ### Windows PowerShell

package/README.md

@@ -40,6 +40,7 @@ Sagaz also guides the user through the process. At the end of each phase, it exp
 - **Durable checkpoints:** long projects can resume across threads and refactors without losing context.
 - **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.
+- **Static site discipline:** hand-built static sites use clean directory URLs by default, GitHub Pages-ready files, and a practical SEO baseline.
 - **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.
 
@@ -85,6 +86,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
@@ -205,7 +208,7 @@ For production-grade work, Sagaz can also apply SRE readiness, DORA metrics, sec
 
 For tool-heavy work, Sagaz uses a tool registry to verify local availability and recommend the right connector or platform before asking permission to install, authenticate, deploy, publish, or modify external resources.
 
-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.
+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. For hand-built static sites, Sagaz should default to clean URLs through directory `index.html` files and verify SEO essentials including canonical URLs, Open Graph/Twitter metadata, Schema.org JSON-LD, sitemap, robots, optimized images, and GitHub Pages files when applicable.
 
 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.
 

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/stack-presets/static-site.md

@@ -6,10 +6,55 @@ Marketing pages, documentation, portfolios, landing pages, and simple content si
 
 ## Default Stack
 
-- Astro, Eleventy, or Vite depending on content needs
+- Hand-built HTML/CSS/JS when the user explicitly wants no static site generator or CMS
+- Astro, Eleventy, or Vite depending on content needs when a generator is acceptable
 - TypeScript when the project has interactive code
 - Netlify, Vercel, Cloudflare Pages, or GitHub Pages
 
+## URL Architecture
+
+- Use clean URLs by default.
+- For hand-built static sites, create each public route as a directory containing `index.html`.
+- Examples:
+  - `/blog/` maps to `blog/index.html`
+  - `/blog/desafios-de-alfabetizacao/` maps to `blog/desafios-de-alfabetizacao/index.html`
+- Do not expose `.html` in navigation, canonical URLs, sitemap URLs, Open Graph URLs, or internal links.
+- Prefer trailing slashes for directory routes because GitHub Pages, Netlify, Cloudflare Pages, and most static hosts serve directory indexes naturally.
+- If converting an existing static site, update all internal links, canonical tags, sitemap entries, and structured data URLs in the same change.
+
+## SEO Baseline
+
+Apply this baseline before delivery unless the user explicitly asks for a draft only:
+
+- Unique `<title>` and meta description for every indexable page.
+- `rel="canonical"` on every indexable page.
+- Open Graph metadata: `og:title`, `og:description`, `og:type`, `og:url`, `og:image`, `og:site_name`, and locale when relevant.
+- Twitter Card metadata for share previews.
+- Schema.org JSON-LD:
+  - `WebSite` for the root site.
+  - `Person`, `Organization`, `LocalBusiness`, or `ProfessionalService` when the site represents a person or business.
+  - `Blog` for the blog listing.
+  - `BlogPosting` or `Article` for posts.
+  - `BreadcrumbList` for blog posts and nested pages.
+- Root `sitemap.xml` containing clean canonical URLs, `lastmod`, and sensible priority/change frequency when known.
+- Root `robots.txt` that allows intended content and references the sitemap.
+- Descriptive `alt` text for meaningful images; empty `alt` only for decorative images.
+- Optimized image formats such as WebP/AVIF plus reasonable dimensions.
+- One clear `h1` per page and semantic heading hierarchy.
+- Accessible navigation, focusable controls, and no hidden text used only for keyword stuffing.
+
+## GitHub Pages Defaults
+
+When the user wants GitHub Pages:
+
+- Add `.nojekyll` for plain static delivery.
+- Add `CNAME` with the custom domain when known.
+- Add `404.html` for GitHub Pages fallback.
+- Use absolute root-relative asset links such as `/assets/styles.css` for nested clean routes.
+- Keep the publishing source compatible with branch deploy from repository root unless the user chooses a custom Actions workflow.
+- Tell the user to configure the custom domain in repository `Settings > Pages` before or alongside DNS changes to reduce takeover risk.
+- For apex domains, use GitHub Pages `A` records or provider-supported `ALIAS`/`ANAME`; for `www`, use `CNAME` to `<user>.github.io` or `<org>.github.io`.
+
 ## Strengths
 
 - Low cost.
@@ -21,3 +66,13 @@ Marketing pages, documentation, portfolios, landing pages, and simple content si
 
 - Dynamic features require external services or backend functions.
 - Content workflows must be planned if nontechnical users edit content.
+- No CMS means blog updates require direct file edits, link updates, sitemap updates, and verification.
+
+## Verification Checklist
+
+- Local route test for `/`, `/blog/`, and representative nested routes.
+- Check that no public internal links contain `.html`.
+- Check broken images and asset loading from nested pages.
+- Parse JSON-LD to verify valid JSON.
+- Confirm sitemap URLs match canonical URLs.
+- Confirm `robots.txt`, `sitemap.xml`, `CNAME`, `.nojekyll`, and `404.html` are present when GitHub Pages is the target.

package/ai-orchestration-ecosystem/workflows/web-production-release.md

@@ -11,7 +11,7 @@ Use this named workflow when the task matches Web Production Release delivery.
 3. Technology: stack recommendation, architecture, deployment tradeoffs.
 4. Design: UX, UI, design system, accessibility, visual quality.
 5. Implementation: build in small verifiable increments.
-6. Verification: tests, QA, visual validation, security review.
+6. Verification: tests, QA, visual validation, SEO checks, accessibility checks, and security review.
 7. Production: readiness, environment variables, deployment, rollback.
 8. GitHub Ops: commit, push, PR, checks, release when approved.
 9. Delivery: final handoff with evidence and residual risks.
@@ -25,6 +25,7 @@ Use this named workflow when the task matches Web Production Release delivery.
 - API contracts.
 - Performance budgets.
 - Accessibility compliance.
+- SEO and share metadata for public websites.
 - Database migrations.
 - Release strategy.
 - DORA metrics.

package/codex-skill/sagaz/SKILL.md

@@ -33,7 +33,9 @@ If navigation is needed, read:
 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. 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.
+15. For hand-built static sites, apply clean URL architecture by default: public routes should be directories with `index.html`, so URLs render as `/page/` and `/blog/post-slug/` rather than exposing `.html`.
+16. For static websites, maximize practical SEO before delivery: unique titles/descriptions, canonical URLs, Open Graph/Twitter metadata, Schema.org JSON-LD, root sitemap, robots sitemap discovery, performance-friendly images, accessibility basics, and deployment-specific files such as `CNAME`, `.nojekyll`, and `404.html` for GitHub Pages when applicable.
+17. Do not declare done without verification evidence proportional to risk.
 
 ## Quick Selection
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sagaz-ai",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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",