gemstack-ai 1.0.1

package/.github/workflows/main-ci.yml

@@ -0,0 +1,32 @@
+name: Main CI
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Full CI
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        node-version: [18.x, 20.x]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Install Dependencies
+        run: npm install
+      - name: Run Native Tests
+        run: npm test
+      - name: Run CI Suite
+        run: npm run ci:all
+      - name: Run Demo Smoke
+        run: npm run ci:demo
+      - name: Validate Package Build
+        run: npm run pack:dry

package/.github/workflows/pr-ci.yml

@@ -0,0 +1,31 @@
+name: PR CI
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Quick CI
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Install Dependencies
+        run: npm install
+      - name: Run Native Tests
+        run: npm test
+      - name: Run CI Suite
+        run: npm run ci:all
+      - name: Run Demo Smoke
+        run: npm run ci:demo
+      - name: Validate Package Build
+        run: npm run pack:dry

package/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write # Requerido para crear GitHub Releases
+
+jobs:
+  publish:
+    name: Publish to NPM and GitHub Releases
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install Dependencies
+        run: npm ci || npm install
+
+      - name: Security Gate - Run CI All
+        run: npm run ci:all
+
+      - name: Pack Package
+        run: npm pack
+        id: pack
+
+      - name: Publish to NPM
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Obtener el nombre del archivo tarball generado por npm pack
+          TARBALL=$(ls gemstack-*.tgz)
+          
+          # Crear el Release oficial de GitHub usando el CLI nativo 'gh'
+          gh release create ${{ github.ref_name }} \
+            --title "Release ${{ github.ref_name }}" \
+            --notes-file RELEASE_NOTES.md \
+            $TARBALL

package/.github/workflows/release-readiness.yml

@@ -0,0 +1,43 @@
+name: Release Readiness
+
+on:
+  workflow_dispatch:
+
+jobs:
+  validate-and-pack:
+    name: Validate and Pack
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+      - name: Install Dependencies
+        run: npm install
+      - name: Run Native Tests
+        run: npm test
+      - name: Run CI Suite
+        run: npm run ci:all
+      - name: Run Demo Smoke
+        run: npm run ci:demo
+      - name: Pack NPM Tarball
+        run: npm pack
+      - name: Test Tarball in Dummy Project
+        run: |
+          mkdir ../gemstack-dummy
+          cd ../gemstack-dummy
+          npm init -y
+          npm install ../Gemstack/gemstack-*.tgz
+          npx gemstack --help
+          npx gemstack init --dry-run
+          npx gemstack init --yes
+          npx gemstack doctor
+          npx gemstack update --dry-run
+      - name: Upload NPM Tarball
+        uses: actions/upload-artifact@v4
+        with:
+          name: gemstack-npm-tarball
+          path: gemstack-*.tgz
+          if-no-files-found: error

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [v0.3.0] - 2026-08-19
+### Added
+- GitHub Actions CI/CD workflows (`pr-ci.yml`, `main-ci.yml`, `release-readiness.yml`).
+- Zero-dependency Node.js CI scripts under `scripts/ci/` (`check-frontmatter.js`, `check-template-clean.js`, `check-mojibake.js`, `check-package-contents.js`, `smoke-cli.js`).
+- Strict repository hygiene validation ensuring `template/` cleanliness before any release.
+- Tarball artifact generation workflow for manual validation.
+- SecureDocs smoke testing embedded in CI (`ci:demo`).
+- `.gitattributes` to enforce consistent EOL globally.
+- README CI badge.
+- Added package artifact validation ensuring no publish secrets.
+- explicitly prevented any npm publish automation for safety.
+
+## [Unreleased]
+### Added
+- Zero-dependency Node.js CLI (`src/cli.js`) to install and update Gemstack via `npx gemstack init` or `gemstack update`.
+- `template/` directory structure separating core framework from source code.
+- Idempotent updates with mandatory `.gemstack/backups` via `src/lib/backup.js`.
+- Manifest tracking (`.gemstack/manifest.json`) using crypto checksums.
+- `gemstack doctor`, `list`, and `show` ported to cross-platform JS.
+- Native unit tests via `node:test`.
+
+## [v0.1.0] - 2026-08-19
+### Added
+- framework Gemstack base (local-first, agent-centric).
+- Antigravity-native `.agents/rules` and `.agents/skills` structure.
+- Spec-Driven Development workflow templates (`specs/current`).
+- Handoff and resume memory system (`handoff.md`).
+- Security/CSO checklist and workflows.
+- SecureDocs demo app (`demo-app/`) to test methodologies.
+- Anti-IDOR smoke tests via `npm run smoke`.
+- PowerShell encoding fix and robust cross-platform CLI helpers (`bin/gemstack`, `bin/gemstack.ps1`).

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.

package/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to Gemstack
+
+First off, thank you for considering contributing to Gemstack! Gemstack is an open-source, local-first framework designed to supercharge AI coding agents with Spec-Driven Development (SDD) and military-grade security out of the box.
+
+## Code of Conduct
+By participating in this project, you agree to abide by our [Code of Conduct](./CODE_OF_CONDUCT.md).
+
+## How Can I Contribute?
+
+### Reporting Bugs
+If you find a bug, please create an issue on GitHub with:
+- The OS and Node.js version.
+- The AI Agent you are using (e.g., Antigravity, Claude, Cursor).
+- Steps to reproduce the behavior.
+- Expected behavior vs actual behavior.
+
+### Suggesting Enhancements
+We love new skills and rules! If you have an idea for a new agentic capability (like our `/qa-visual` or `/swarm`), open a discussion or issue describing:
+- The problem it solves.
+- The proposed `SKILL.md` or `RULE.md` format.
+
+### Pull Requests
+1. Fork the repo and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. If you've changed the agent skills in `template/`, make sure you run `npm run ci:all` to verify that `gemstack update` logic remains intact.
+4. Ensure the test suite passes (`npm test`).
+5. Issue that pull request!
+
+## Local Development Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/rtorrescodes/Gemstack.git
+   cd Gemstack
+   ```
+
+2. **Install dependencies:**
+   Gemstack is zero-dependencies for the end-user, but we use native Node `test` runner and some standard scripts for development.
+   ```bash
+   npm install
+   ```
+
+3. **Testing CLI changes locally:**
+   Link the package globally to test it on your system:
+   ```bash
+   npm link
+   ```
+   Now you can run `gemstack init` in any dummy directory to test scaffolding.
+
+4. **Running the CI suite:**
+   Before committing, always run:
+   ```bash
+   npm run ci:all
+   ```
+   This will run our full suite of syntax checks, mojibake prevention, frontmatter validation, and CLI smoke tests.
+
+## Architecture Guidelines
+- **Zero-Dependency Core**: The end-user's `template/` output must never require `package.json` dependencies unless explicitly requested by the user.
+- **Language Agnostic**: Agent skills must work regardless of whether the user writes in Python, Node, Go, or Rust.
+- **Security First**: Any new feature must respect the `03-gemstack-security.md` rules.
+
+Welcome to the team!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gemstack Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MANUAL.md

@@ -0,0 +1,99 @@
+# 📖 Manual Oficial de Gemstack (La Guía Definitiva)
+
+¡Bienvenido a **Gemstack**! Si estás leyendo esto, probablemente sientes curiosidad sobre cómo programar mejor con Inteligencia Artificial. Este manual está diseñado para explicarte qué es este proyecto, por qué existe y cómo usarlo paso a paso, de manera sencilla.
+
+---
+
+## 1. ¿Qué es Gemstack?
+
+Hoy en día, herramientas como Copilot, Cursor, o Antigravity son increíbles escribiendo código, pero **tienen un problema**: son caóticas. Si les pides un sistema complejo, a menudo olvidan requerimientos, introducen vulnerabilidades de seguridad y pierden el hilo del proyecto.
+
+**Gemstack NO es un framework de código** (no compite con React, Django o Laravel). 
+Gemstack es un **"Sistema Operativo para Inteligencias Artificiales"**. 
+
+Es una herramienta de cero dependencias (funciona en cualquier lenguaje y computadora) que inyecta un "cerebro", disciplina y reglas militares en tu repositorio. Cuando instalas Gemstack, obligas a la IA a dejar de improvisar y comenzar a trabajar como un Ingeniero Senior de Software bajo procesos estrictos.
+
+---
+
+## 2. Instalación: Tu Primer Paso
+
+No necesitas instalar librerías pesadas. En cualquier proyecto (sea nuevo o uno que ya lleve meses de desarrollo), abre tu terminal y ejecuta:
+
+```bash
+npx gemstack init
+```
+
+**¿Qué hace esto?**
+No tocará tu código fuente. Creará silenciosamente carpetas ocultas (`.agents/`, `specs/`, `docs/`) que contienen las reglas, habilidades y flujos de trabajo que la IA debe leer antes de ayudarte a programar. ¡Y listo! Tu proyecto ahora tiene un "cerebro" estructurado.
+
+---
+
+## 3. El Flujo de Trabajo (Spec-Driven Development)
+
+Para usar Gemstack, no programas directamente. Escribes **especificaciones** en tu chat de IA y dejas que los agentes sigan un proceso ordenado. Así es como se construye una funcionalidad:
+
+### Paso A: Ideación (`/spec`)
+Abre tu chat con la IA (Cursor, Antigravity, Claude) y dile:
+> *"Quiero crear un sistema de login. Ejecuta `/spec`"*
+
+El agente **Product Manager** analizará tu idea, te hará preguntas clave y escribirá un documento Markdown (`specs/current/spec.md`) detallando exactamente cómo debe funcionar, sin escribir ni una línea de código aún.
+
+### Paso B: Planificación (`/plan`)
+Una vez que apruebes el Spec, dile a la IA:
+> *"Perfecto, ejecuta `/plan`"*
+
+El agente **Arquitecto** leerá el Spec y decidirá qué archivos hay que crear, qué base de datos usar y cómo estructurarlo técnicamente (`specs/current/plan.md`).
+
+### Paso C: Ejecución (`/tasks`)
+Dile a la IA:
+> *"Haz el desglose, `/tasks`"*
+
+Se generará una lista de tareas (`[ ]`, `[/]`, `[x]`). Ahora simplemente dile a la IA: *"Empieza a ejecutar la tarea 1"*. La IA escribirá el código de forma ordenada y controlada.
+
+---
+
+## 4. Los Súper Poderes de Gemstack
+
+Gemstack viene con funcionalidades avanzadas (Skills) que puedes invocar como comandos en tu chat:
+
+### 🛡️ Seguridad Militar (`/cso`)
+Dile a la IA: *"Ejecuta `/cso`"*. El Chief Security Officer auditará tu código. Gemstack tiene leyes estrictas implantadas en su núcleo (AppSec Nivel 2 y DevOps). Si tienes una contraseña expuesta, o tu base de datos es vulnerable a un ataque de fuerza bruta, el agente detendrá todo y te obligará a parcharlo.
+
+### 🪝 Prevención Activa (Git Hooks)
+Gemstack se asegura de que tú, como humano, tampoco cometas errores. Al hacer `npx gemstack init`, se instala un guardián invisible. Si intentas hacer un `git commit` y por error incluiste una llave de Amazon Web Services (AWS) o un archivo `.env`, Gemstack bloqueará el commit en tu terminal y te regañará.
+
+### 📊 Dashboard Interactivo (`/dashboard`)
+¿Perdido en el código? Dile a tu chat de IA (si usas Antigravity):
+> *"Ejecuta `/dashboard`"*
+
+La IA leerá tu lista de tareas y generará una interfaz gráfica incrustada en tu chat mostrándote una barra de progreso, el estado de tu seguridad y las tareas pendientes.
+
+### 🔌 Instalación de Skills Externos
+Gemstack es extensible. Si alguien en internet creó un súper agente especialista en Python, puedes descargarlo a tu proyecto directamente desde la terminal:
+```bash
+npx gemstack install https://raw.githubusercontent.com/usuario/repo/main/SKILL.md
+```
+
+### 🤖 Servidor MCP (Para IAs Externas)
+Si usas Claude Desktop u otro cliente que soporte **Model Context Protocol (MCP)**, puedes configurar Gemstack como una de sus herramientas nativas. Simplemente configura el servidor ejecutando en tu cliente: `npx gemstack mcp`. La IA podrá "llamar" a Gemstack directamente por debajo de la mesa para preguntarle cuáles son tus tareas actuales y reglas de seguridad sin que tengas que decirle nada.
+
+---
+
+## 5. Terminando tu Día (`/handoff`)
+
+Cuando termines de trabajar, dile a la IA:
+> *"He terminado por hoy. Ejecuta `/handoff`"*
+
+La IA escribirá un archivo `handoff.md` resumiendo exactamente en qué te quedaste, qué bugs hay pendientes y qué debes hacer mañana. 
+
+Al día siguiente (o si otro desarrollador toma tu proyecto), el primer mensaje al chat debe ser:
+> *"Hola, soy nuevo aquí. Ejecuta `/resume`"*
+
+La IA leerá el Handoff y te pondrá al día instantáneamente.
+
+---
+
+## Resumen Final
+Gemstack te convierte en un Director de Orquesta. En lugar de pelear con el código línea por línea, tú diriges a los agentes (Product Manager, CSO, QA) utilizando comandos simples (`/spec`, `/plan`, `/cso`, `/dashboard`). 
+
+¡Disfruta construyendo software de grado empresarial a la velocidad de la luz!

package/README.md

@@ -0,0 +1,130 @@
+<div align="center">
+  <img src="https://via.placeholder.com/150x150/1a1a2e/ffffff?text=GS" alt="Gemstack Logo" width="120" height="120" />
+  <h1>Gemstack</h1>
+  <p><b>The Local-First Agentic Framework for Spec-Driven Development</b></p>
+
+  [![npm version](https://img.shields.io/npm/v/gemstack.svg?style=flat-square)](https://www.npmjs.com/package/gemstack)
+  [![CI Build](https://img.shields.io/github/actions/workflow/status/rtorrescodes/Gemstack/main-ci.yml?style=flat-square&branch=main)](https://github.com/rtorrescodes/Gemstack/actions)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+  [![Security Shield](https://img.shields.io/badge/Security-Military--Grade-red.svg?style=flat-square)](#military-grade-security-shield)
+
+> **💡 ¿No sabes por dónde empezar o cómo funciona esto?**  
+> 👉 [**¡Lee el Manual de Usuario Interactivo (La Guía Definitiva)!**](MANUAL.md) 👈
+</div>
+
+---
+
+Gemstack is a zero-dependency, local-first framework designed to supercharge your AI Coding Agents (like Google Antigravity, Claude, Cursor, or Aider). 
+
+Instead of letting AI write code blindly in a chaotic chat window, Gemstack installs a "Brain" directly into your repository. It enforces **Spec-Driven Development (SDD)**, injecting strict rules, autonomous skills, and military-grade security into the AI's context.
+
+## ✨ Features
+
+- 🧠 **Spec-Driven Development (SDD)**: The AI is physically prevented from hallucinating code without writing and getting approval for a `spec.md`, `plan.md`, and `tasks.md` first.
+- 🛡️ **Military-Grade Security**: Includes a built-in Chief Security Officer (`gemstack-cso`) and immutable Constitution Rules that force the AI to respect OWASP, zero-trust secrets, and multi-tenant isolation.
+- 🐝 **Swarm Architecture**: Tag tasks with `[P]` and invoke `/swarm` to watch the AI spawn parallel subagents to code your app simultaneously.
+- 🏥 **Self-Healing CI/CD**: Run `/heal` when GitHub Actions fails. The AI will autonomously read the CI logs, write the patch, and push the fix.
+- 👁️ **Visual QA Automation**: The `/qa-visual` skill instructs the agent to write and execute ephemeral Playwright scripts in an isolated sandbox to visually verify UI criteria.
+- 📦 **Zero Dependencies**: Gemstack's footprint is just standard Markdown and JSON files. No heavy NPM packages polluting your production bundle.
+
+## 🚀 Quickstart
+
+Start a new project or upgrade an existing one in seconds:
+
+```bash
+# Initialize Gemstack in your current repository
+npx gemstack init
+```
+
+This will generate the `.agents/`, `.gemstack/`, and `specs/` directories.
+
+To ensure your framework is healthy or to check for manual tampering:
+```bash
+npx gemstack doctor
+```
+
+To update your project when Gemstack releases new Agent Skills:
+```bash
+npx gemstack update
+```
+
+## 🧠 How it Works
+
+Gemstack works by providing an **Operating System** for your LLM via markdown files. When you chat with your agent, you use "Slash Commands" that map to specific files in your `.agents/skills/` directory.
+
+### The SDD Workflow
+1. `/specify I want to build a real-time chat app` -> The AI creates `specs/[feature]/spec.md`.
+2. `/plan` -> The AI reads the spec and writes technical architecture in `plan.md`.
+3. `/tasks` -> The AI breaks the plan into an actionable, parallelizable checklist.
+4. **Code!** -> The AI executes the tasks.
+5. `/review` -> The AI reviews the diffs against the `03-gemstack-security.md` rules.
+6. `/handoff` -> The AI saves its memory to `handoff.md` so you can close your laptop and resume flawlessly tomorrow.
+
+## 🛡️ Military-Grade Security Shield
+
+Gemstack ships with `03-gemstack-security.md` and `04-gemstack-infrastructure.md`, rulebooks extracted from high-compliance SaaS and Cloud Native environments (OWASP, NIST). When you run `/cso` or `/review`, the AI strictly checks for:
+- **AppSec (Level 2)**: IDOR Protection, Race Condition prevention, CSRF/SSRF blocking, Rate Limiting, and Audit Trails.
+- **Zero Trust Secrets**: Hardcoded keys are blocked.
+- **DevSecOps & Infra**: Enforces Immutable Infrastructure (Docker/Terraform), Private Subnets (VPC), IAM Least Privilege, and Cloud Secret Managers.
+- **Server-Side Validation**: Complete distrust of frontend state.
+
+## 🐝 Advanced Autonomy (The WOW Update)
+
+Gemstack isn't just passive documents; it actively orchestrates agentic capabilities:
+
+| Command | Action |
+|---------|--------|
+| `/swarm` | Orchestrates parallel subagents for tasks marked `[P]` |
+| `/qa-visual` | Spawns sandbox browsers to visually assert Acceptance Criteria |
+| `/dashboard` | Generates a rich, interactive inline UI of your project's progress |
+| `/heal` | Hooks into GitHub CLI (`gh`) to read failing CI logs and auto-push fixes |
+| `/sandbox` | Wraps risky AI execution inside an ephemeral Docker container |
+
+## 🪝 Active Security (Git Hooks)
+
+Gemstack ships with native, zero-dependency Git hooks. Run `npx gemstack hooks` (or just `npx gemstack init`) to install a local `pre-commit` hook that automatically blocks commits containing:
+- Exposed `.env` files.
+- Hardcoded secrets (Stripe, AWS, JWT keys).
+- Unresolved merge conflict markers (`<<<<<<< HEAD`).
+
+## 🔌 Ecosystem & Plugins (Skill Market)
+
+You can install agent skills created by the community directly into your project using the `install` command. Gemstack will fetch the `SKILL.md`, parse its metadata, and integrate it into your AI's brain automatically:
+```bash
+npx gemstack install https://raw.githubusercontent.com/community/gemstack-skills/main/django-expert/SKILL.md
+```
+
+## 🤖 MCP Server (Model Context Protocol)
+
+Gemstack ships with a built-in MCP server that exposes the SDD state of your project to any MCP-compliant AI client (like Claude Desktop or Cursor). 
+
+Add the following to your MCP client configuration:
+```json
+{
+  "mcpServers": {
+    "gemstack": {
+      "command": "npx",
+      "args": ["gemstack", "mcp"]
+    }
+  }
+}
+```
+
+## 📚 Documentation
+
+Dive deeper into the Gemstack architecture:
+- [📖 **Manual de Usuario**](MANUAL.md) - The Definitive Guide for beginners.
+- [🧠 Spec-Driven Development](docs/spec-driven-development.md) - How the SDD loop works.
+- [Available Skills](docs/skills.md)
+- [Security Model](docs/security.md)
+- [Handoff Protocol](docs/handoff.md)
+
+## 🤝 Contributing
+
+We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) to learn how to add new agentic skills, improve the Node CLI, or enhance the SDD Constitution.
+
+Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
+
+## 📄 License
+
+MIT License. See [LICENSE](LICENSE) for details.