docs: align core guides with sidecar and Spec Kit base

Author: juanklagos

README.es.md

@@ -1,14 +1,14 @@
 <div align="center">
   <h1>🌱 Spec-Driven Development Template</h1>
-  <p><b>Inicia proyectos con disciplina basada en especificaciones y guía amigable para IA.</b></p>
+  <p><b>Inicia proyectos con disciplina basada en especificaciones, GitHub Spec Kit como flujo base y guía amigable para IA.</b></p>
 
   <p>
     <a href="./README.md"><img src="https://img.shields.io/badge/🇺🇸_English-Read-blue?style=for-the-badge" alt="English"></a>
     <a href="./README.es.md"><img src="https://img.shields.io/badge/🇪🇸_Español-Activo-green?style=for-the-badge" alt="Español"></a>
   </p>
 
   <p>
-    <img src="https://img.shields.io/badge/version-v1.3.0-blue?style=for-the-badge" alt="Version">
+    <img src="https://img.shields.io/badge/version-v1.4.0-blue?style=for-the-badge" alt="Version">
     <a href="./START_HERE_NON_TECH.md"><img src="https://img.shields.io/badge/🧑‍💼_NO_TÉCNICO-Iniciar-green?style=for-the-badge" alt="Inicio no técnico"></a>
     <a href="./AI_START_HERE.md"><img src="https://img.shields.io/badge/🤖_INICIO_IA-Abrir-purple?style=for-the-badge" alt="AI Start"></a>
     <a href="./QUICKSTART.md"><img src="https://img.shields.io/badge/🚀_QUICKSTART-5_Minutos-ff6b35?style=for-the-badge" alt="Quickstart"></a>
@@ -21,14 +21,19 @@
 
 ## ⚡ Empieza en 30 segundos
 
+Este framework usa [GitHub Spec Kit](https://github.com/github/spec-kit) como referencia principal del flujo de trabajo.
+Usa este repositorio como la capa práctica alrededor de esa base:
+- GitHub Spec Kit = motor de flujo de referencia
+- este repositorio = estructura inicial, instalación sidecar, reglas para IA, MCP y guía del proyecto
+
 1. Abre [AI_START_HERE.md](./AI_START_HERE.md)
    o [START_HERE_NON_TECH.md](./START_HERE_NON_TECH.md) si no eres técnico.
 2. Copia y pega este prompt:
 
 ```text
 Usando https://github.com/juanklagos/spec-driven-development-template, guíame paso a paso con SDD para mi proyecto.
 Mi proyecto es: [explica tu proyecto en lenguaje simple].
-Si mi proyecto es nuevo, inicializa desde este template.
+Si mi proyecto es nuevo, inicializa desde este template y GitHub Spec Kit como flujo base.
 Si ya existe, adáptalo sin romper el comportamiento actual.
 No hay código sin spec aprobada y plan consistente.
 ```
@@ -122,6 +127,7 @@ Archivos de referencia:
 ## 🧭 Template vs proyecto real
 
 - Este repositorio es un **marco/template**.
+- Usa **GitHub Spec Kit como referencia operativa base** para la secuencia de comandos y el flujo SDD.
 - La ruta profesional de producto es: raíz del framework + `packages/sdd-core` + `packages/sdd-mcp`.
 - El trabajo de producto debe ejecutarse en tu proyecto destino usando esta estructura.
 - Para proyectos reales, prefiere un sidecar compacto `spec/` dentro del proyecto y mantén el código en la raíz del proyecto.
@@ -157,6 +163,8 @@ flowchart TD
   A --> F["scripts/"]
   A --> G["packages/"]
   A --> H["www/"]
+  H --> I["proyecto-destino/"]
+  I --> J["spec/"]
 ```
 
 Carpetas obligatorias:
@@ -165,6 +173,11 @@ Carpetas obligatorias:
 - `bitacora/`: trazabilidad y handoffs
 - `docs/`: guías y referencias
 
+En proyectos reales, esas carpetas SDD normalmente viven dentro de `./spec/`:
+- `./spec/idea/`
+- `./spec/specs/`
+- `./spec/bitacora/`
+
 Paquete obligatorio por feature:
 1. `spec.md`
 2. `plan.md`
@@ -219,7 +232,7 @@ Paquete obligatorio por feature:
 - Roadmap: [Roadmap público](./docs/es/35-roadmap-publico.md)
 - Organización: [Mapa del proyecto](./docs/es/42-mapa-organizacion-proyecto.md)
 - Kit de medios: [Assets y posicionamiento](./docs/es/38-kit-medios.md)
-- Preparación próxima release: [v1.3.0](./docs/es/46-preparacion-v1.3.0.md)
+- Preparación histórica de release: [notas de v1.3.0](./docs/es/46-preparacion-v1.3.0.md)
 - Calidad: [Checklists por etapa](./docs/es/21-checklists-calidad-por-etapa.md) · [ADR](./docs/es/24-decisiones-de-arquitectura.md)
 
 ---

README.md

@@ -1,14 +1,14 @@
 <div align="center">
   <h1>🌱 Spec-Driven Development Template</h1>
-  <p><b>Start projects with specification-first discipline and AI-friendly guidance.</b></p>
+  <p><b>Start projects with specification-first discipline, GitHub Spec Kit as the base workflow, and AI-friendly guidance.</b></p>
 
   <p>
     <a href="./README.md"><img src="https://img.shields.io/badge/🇺🇸_English-Active-blue?style=for-the-badge" alt="English"></a>
     <a href="./README.es.md"><img src="https://img.shields.io/badge/🇪🇸_Español-Read-green?style=for-the-badge" alt="Español"></a>
   </p>
 
   <p>
-    <img src="https://img.shields.io/badge/version-v1.3.0-blue?style=for-the-badge" alt="Version">
+    <img src="https://img.shields.io/badge/version-v1.4.0-blue?style=for-the-badge" alt="Version">
     <a href="./START_HERE_NON_TECH.md"><img src="https://img.shields.io/badge/🧑‍💼_NON--TECH-Start-green?style=for-the-badge" alt="Non Technical Start"></a>
     <a href="./AI_START_HERE.md"><img src="https://img.shields.io/badge/🤖_AI_START-Open-purple?style=for-the-badge" alt="AI Start"></a>
     <a href="./QUICKSTART.md"><img src="https://img.shields.io/badge/🚀_QUICKSTART-5_Minutes-ff6b35?style=for-the-badge" alt="Quickstart"></a>
@@ -21,14 +21,19 @@
 
 ## ⚡ Start in 30 Seconds
 
+This framework uses [GitHub Spec Kit](https://github.com/github/spec-kit) as the primary workflow reference.
+Use this repository as the practical layer around that base:
+- GitHub Spec Kit = reference workflow engine
+- this repository = starter structure, sidecar installation, AI rules, MCP, and project guidance
+
 1. Open [AI_START_HERE.md](./AI_START_HERE.md)
    or [START_HERE_NON_TECH.md](./START_HERE_NON_TECH.md) if you are non-technical.
 2. Copy/paste this prompt:
 
 ```text
 Using https://github.com/juanklagos/spec-driven-development-template, guide me step by step with SDD for my project.
 My project is: [describe your project in plain language].
-If my project is new, initialize from this template.
+If my project is new, initialize from this template and GitHub Spec Kit as the base workflow.
 If it already exists, adapt it without breaking current behavior.
 No code before approved spec and consistent plan.
 ```
@@ -122,6 +127,7 @@ Reference files:
 ## 🧭 Template vs Real Project
 
 - This repository is a **framework/template**.
+- It uses **GitHub Spec Kit as the base operating reference** for the command sequence and SDD flow.
 - The professional productization path is: framework root + `packages/sdd-core` + `packages/sdd-mcp`.
 - Your product work should run in your target project using this structure.
 - For real projects, prefer a compact `spec/` sidecar inside the project and keep code in the project root.
@@ -157,6 +163,8 @@ flowchart TD
   A --> F["scripts/"]
   A --> G["packages/"]
   A --> H["www/"]
+  H --> I["target-project/"]
+  I --> J["spec/"]
 ```
 
 Mandatory folders:
@@ -165,6 +173,11 @@ Mandatory folders:
 - `bitacora/`: execution trace and handoffs
 - `docs/`: usage guides and references
 
+For real target projects, those SDD folders usually live under `./spec/`:
+- `./spec/idea/`
+- `./spec/specs/`
+- `./spec/bitacora/`
+
 Mandatory spec bundle (for each feature):
 1. `spec.md`
 2. `plan.md`
@@ -219,7 +232,7 @@ Mandatory spec bundle (for each feature):
 - Roadmap: [Public Roadmap](./docs/en/35-public-roadmap.md)
 - Organization: [Project Map](./docs/en/42-project-organization-map.md)
 - Media Kit: [Assets and Positioning](./docs/en/38-media-kit.md)
-- Next Release Prep: [v1.3.0](./docs/en/46-v1.3.0-preparation.md)
+- Historical Release Prep: [v1.3.0 prep notes](./docs/en/46-v1.3.0-preparation.md)
 - Quality: [Stage Checklists](./docs/en/21-quality-checklists-by-stage.md) · [ADR](./docs/en/24-architecture-decisions.md)
 
 ---

docs/README.md

@@ -10,7 +10,7 @@ Start here / Empieza aquí:
 ```text
 Using https://github.com/juanklagos/spec-driven-development-template, create everything needed to carry out my project end-to-end.
 My project is: [describe your project in plain language].
-If my project is new, initialize it with this template + GitHub Spec Kit.
+If my project is new, initialize it with this template, using GitHub Spec Kit as the base workflow.
 If it already exists, adapt it to idea/specs/bitacora without breaking behavior.
 Guide me by level (beginner/intermediate/advanced) using simple language.
 ```

docs/en/01-structure.md

@@ -26,19 +26,31 @@ Recommended target-project shape:
 - project root = app code
 - `spec/` = SDD operating system
 
+That means:
+- `spec/idea/`
+- `spec/specs/`
+- `spec/bitacora/`
+
+GitHub Spec Kit remains the base workflow reference for the project.
+This repository adds the structure, sidecar mode, AI rules, and guidance around that base.
+
 
 
 ## idea
 
-Path: `idea/`
+Path:
+- framework root mode: `idea/`
+- real project sidecar mode: `spec/idea/`
 
 Main file:
 
 - `IDEA_GENERAL.md`: defines project problem, goal, scope, users, risks, and completion criteria.
 
 ## specs
 
-Path: `specs/`
+Path:
+- framework root mode: `specs/`
+- real project sidecar mode: `spec/specs/`
 
 Main files:
 
@@ -54,7 +66,9 @@ Each specification lives in a numbered folder:
 
 ## bitacora
 
-Path: `bitacora/`
+Path:
+- framework root mode: `bitacora/`
+- real project sidecar mode: `spec/bitacora/`
 
 Subfolders:
 
@@ -72,7 +86,9 @@ Contains educational documentation for this system.
 
 ## scripts
 
-Path: `scripts/`
+Path:
+- framework root mode: `scripts/`
+- real project sidecar mode: `spec/scripts/`
 
 Contains scripts to initialize this structure in other repositories.
 

docs/en/34-launch-kit.md

@@ -17,13 +17,13 @@ flowchart LR
 ## Short update
 
 ```text
-Spec-Driven Development Template now includes a real MCP server.
+Spec-Driven Development Template now defaults to a clean `spec/` sidecar architecture for real projects.
 
-New in v1.3.0:
-- local `sdd-mcp` server
-- stdio + Streamable HTTP
-- copy-paste configs for Cursor, Claude Code, and Codex
-- active project resources for idea, specs, logbook, and handoffs
+New in v1.4.0:
+- compact `spec/` sidecar prompts for AI tools
+- cleaner project layout for advanced or existing codebases
+- MCP contracts aligned with sidecar projects
+- link-check and MCP CI fixes for the new architecture
 
 Repository:
 https://github.com/juanklagos/spec-driven-development-template
@@ -32,19 +32,20 @@ https://github.com/juanklagos/spec-driven-development-template
 ## LinkedIn post
 
 ```text
-I just shipped v1.3.0 of my Spec-Driven Development Template.
+I just shipped v1.4.0 of my Spec-Driven Development Template.
 
 This repository is evolving into an operational SDD framework, not just a documentation starter.
 
 What it now includes:
 - GitHub Spec Kit as the primary reference flow
+- `spec/` sidecar as the professional default for real projects
 - multi-agent operating rules
-- runnable work defaults cleanly to ./www/<project-name> while still supporting external target paths
+- clean internal container support under ./www/<project-name> when the project lives inside the template
 - local MCP server (`sdd-mcp`)
 - stdio + Streamable HTTP
 - typed SDD core
 - MCP integration tests and CI
-- copy-paste client configs for Cursor, Claude Code, and Codex
+- copy-paste sidecar prompts so AI tools stop copying the whole repository into advanced projects
 
 Repository:
 https://github.com/juanklagos/spec-driven-development-template
@@ -55,5 +56,5 @@ The goal is to reduce friction from idea -> spec -> plan -> tasks -> validation,
 ## Short release note
 
 ```text
-v1.3.0 strengthens the framework as an easier operational SDD system: easy MCP guides, hosted onboarding model, client visual examples, package version alignment, and a clearer path for non-technical adoption.
+v1.4.0 makes the framework cleaner to apply in real projects: `spec/` sidecar by default, GitHub Spec Kit as the base workflow reference, MCP behavior aligned with sidecar projects, and exact prompts that stop AI tools from copying the whole repository into advanced codebases.
 ```

docs/en/35-public-roadmap.md

@@ -8,25 +8,27 @@ This roadmap makes the next product steps explicit so users know where the frame
 
 ```mermaid
 flowchart LR
-  A["v1.3.0"] --> B["v1.4.0"]
-  B --> C["v1.5.0"]
+  A["v1.4.0"] --> B["v1.5.0"]
+  B --> C["v1.6.0"]
 ```
 
 ## Current state
 
 Released:
-- `v1.3.0`
+- `v1.4.0`
 
 Now available:
 - SDD framework with multi-agent policy
-- recommended default workspace in `./www/<project-name>/`, with support for external target paths
+- GitHub Spec Kit as the base workflow reference
+- recommended `spec/` sidecar for real target projects
+- `./www/<project-name>/` as the clean internal container when the project lives inside this repository
 - typed `sdd-core`
 - local `sdd-mcp`
 - `stdio` + `Streamable HTTP`
 - MCP tools, resources, prompts, smoke tests, and integration tests
 - client setup recipes and package version alignment
 
-## v1.4.0
+## v1.5.0
 
 Focus: hosted onboarding hardening and richer operator experience.
 
@@ -37,7 +39,7 @@ Planned:
 - tested setup guides with screenshots for Cursor, Claude Code, and Codex
 - stronger release automation and packaging guidance
 
-## v1.5.0
+## v1.6.0
 
 Focus: framework standardization and publishable MCP packaging.
 

docs/en/37-versioning-strategy.md

@@ -18,9 +18,9 @@ flowchart LR
 - `@sdd/sdd-core` and `@sdd/sdd-mcp` should stay aligned with the repository minor release
 
 Current alignment:
-- framework: `1.3.0`
-- `@sdd/sdd-core`: `1.3.0`
-- `@sdd/sdd-mcp`: `1.3.0`
+- framework: `1.4.0`
+- `@sdd/sdd-core`: `1.4.0`
+- `@sdd/sdd-mcp`: `1.4.0`
 
 ## Practical release policy
 

docs/es/01-estructura.md

@@ -26,19 +26,31 @@ Forma recomendada del proyecto destino:
 - raíz del proyecto = código app
 - `spec/` = sistema operativo SDD
 
+Eso significa:
+- `spec/idea/`
+- `spec/specs/`
+- `spec/bitacora/`
+
+GitHub Spec Kit sigue siendo la referencia base del flujo de trabajo.
+Este repositorio agrega la estructura, el modo sidecar, las reglas para IA y la guía alrededor de esa base.
+
 
 
 ## Carpeta idea
 
-Ruta: `idea/`
+Ruta:
+- modo raíz del framework: `idea/`
+- modo sidecar en proyecto real: `spec/idea/`
 
 Archivo principal:
 
 - `IDEA_GENERAL.md`: define el problema, objetivo, alcance, usuarios, riesgos y criterio de terminado.
 
 ## Carpeta specs
 
-Ruta: `specs/`
+Ruta:
+- modo raíz del framework: `specs/`
+- modo sidecar en proyecto real: `spec/specs/`
 
 Archivos principales:
 
@@ -54,7 +66,9 @@ Cada especificación vive en una carpeta enumerada:
 
 ## Carpeta bitacora
 
-Ruta: `bitacora/`
+Ruta:
+- modo raíz del framework: `bitacora/`
+- modo sidecar en proyecto real: `spec/bitacora/`
 
 Subcarpetas:
 
@@ -72,7 +86,9 @@ Contiene la documentación pedagógica del sistema.
 
 ## Carpeta scripts
 
-Ruta: `scripts/`
+Ruta:
+- modo raíz del framework: `scripts/`
+- modo sidecar en proyecto real: `spec/scripts/`
 
 Contiene scripts para instalar esta estructura en otro repositorio.