context-map-ai 2.3.0__tar.gz → 2.4.0__tar.gz

context_map_ai-2.4.0/.agents/skills/contextmap/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: contextmap
+description: Protocolo, flujos y comandos esenciales para gobernar el contexto, consultar la memoria permanente y mantener vivo el grafo del proyecto con ContextMap IA.
+---
+
+# Skill de ContextMap IA — ContextMap
+
+Esta skill proporciona las directivas operativas para interactuar con la memoria permanente, los documentos de referencia y el grafo conceptual de **ContextMap**.
+
+## Comandos Esenciales
+
+```bash
+# 1. Poner todo el contexto al día en un solo paso (scan + build con preservación + auto-ingesta + check)
+ctxmap refresh .
+
+# 2. Ingerir documentos brutos manualmente (MD, TXT, PDF)
+ctxmap ingest .context-map/raw/docs/
+
+# 3. Verificar la salud, integridad y enlaces rotos del vault
+ctxmap check .
+
+# 4. Sincronizar memoria personal / multi-proyecto
+ctxmap personal sync
+
+# 5. Consultar decisiones o conocimiento histórico
+ctxmap personal query "tema de consulta"
+```
+
+## Protocolo de Inicio y Memoria Viva para Agentes
+
+1. **Inspeccionar Brief**: Leer `.context-map/CONTEXT.md` (identidad, propósito, métricas y estado).
+2. **Consultar Documentos y Backlog**: Revisar `.context-map/vault-ContextMap/3.2-DOCUMENTOS/`, `7.0-MANUAL/BACKLOG.md` y notas de diario recientes.
+3. **Memoria Viva Multicanal**: Para incorporar contexto externo (conversaciones, transcripciones o especificaciones), colócalos en `.context-map/chats/` o `.context-map/raw/docs/`. `ctxmap refresh .` los asimilará automáticamente.
+4. **Verificar Antes de Commit**:
+   - Tests: `python -m pytest`
+   - Refrescar grafo y vault: `ctxmap refresh .`
+   - Sin archivos sueltos en raíz.

{context_map_ai-2.3.0 → context_map_ai-2.4.0}/.github/copilot-instructions.md

@@ -18,7 +18,7 @@
 
 # GitHub Copilot — Instrucciones para ContextMap
 
-> Generado automáticamente por **ContextMap** (2026-08-21).
+> Generado automáticamente por **ContextMap** (2026-09-23).
 
 ## Antes de sugerir código
 

{context_map_ai-2.3.0 → context_map_ai-2.4.0}/.github/workflows/ci.yml

@@ -9,7 +9,11 @@ on:
 jobs:
   test:
     name: Tests (pytest)
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
     steps:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v5
@@ -32,3 +36,17 @@ jobs:
         run: uv sync --dev --all-extras
       - name: Ruff check
         run: uv run ruff check context_map/
+
+  typecheck:
+    name: Type check (mypy · bloqueante)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Instalar dependencias
+        run: uv sync --dev --all-extras
+      - name: mypy
+        run: uv run mypy context_map/
+

{context_map_ai-2.3.0 → context_map_ai-2.4.0}/.gitignore

@@ -52,5 +52,11 @@ Thumbs.db
 # Context Map (generated)
 .context-map/
 
+# Respaldos automáticos de `ctxmap adapt --overwrite`
+*.bak
+
 # Logs
 *.log
+
+# Scratch and test workspace
+.work/

context_map_ai-2.4.0/.hermes/workflows/contextmap.yaml

@@ -0,0 +1,21 @@
+# Hermes Workflow — ContextMap IA Governance
+version: "1.0"
+name: "contextmap-governance"
+description: "Flujo automatizado de contexto y calidad para ContextMap"
+
+steps:
+  - name: "Ponerse en contexto"
+    action: "read_file"
+    target: ".context-map/CONTEXT.md"
+
+  - name: "Ejecutar pruebas unitarias"
+    action: "run_command"
+    command: "python -m pytest"
+
+  - name: "Sincronizar memoria viva"
+    action: "run_command"
+    command: "ctxmap refresh ."
+
+  - name: "Control de calidad"
+    action: "run_command"
+    command: "ctxmap check ."

{context_map_ai-2.3.0 → context_map_ai-2.4.0}/AGENTS.md

@@ -55,24 +55,25 @@ Cualquier agente que tome una tarea en este proyecto **DEBE** seguir estos pasos
    mi-app-utm) o por un vault que no es este, dilo ANTES de responder — nunca
    respondas con el contexto de otro proyecto.
 2. **Leer el Brief Ejecutivo**:
-   Consultar [.context-map/CONTEXT.md](file:///c:/Users/jose.cespedes/Desktop/PruebaContext/.context-map/CONTEXT.md) para conocer las métricas, riesgos críticos y tareas pendientes.
+   Consultar [.context-map/CONTEXT.md](file:///.context-map/CONTEXT.md) para conocer las métricas, riesgos críticos y tareas pendientes.
 3. **Comprobar la FRESCURA del contexto**: si el brief avisa que el diario manual
    es más nuevo que el build (sección "Estado del Contexto"), ejecuta
    `ctxmap refresh .` ANTES de responder sobre el estado del proyecto.
-4. **Leer los PENDIENTES REALES**: además del backlog generado (5.0-BACKLOG),
-   revisa SIEMPRE `.context-map/vault-ContextMap/7.0-MANUAL/BACKLOG.md` (si existe)
-   y el diario más reciente (`7.0-MANUAL/Diario/`). Los pendientes conversados con
-   el usuario viven ahí.
+4. **Leer los PENDIENTES REALES y DOCUMENTOS**: además del backlog generado (5.0-BACKLOG),
+   revisa SIEMPRE `.context-map/vault-ContextMap/7.0-MANUAL/BACKLOG.md`, los documentos de dominio en `.context-map/vault-ContextMap/3.2-DOCUMENTOS/`
+   y el diario más reciente (`7.0-MANUAL/Diario/`). Los pendientes conversados y el conocimiento documental viven ahí.
 5. **Revisar el Backlog y Vault**:
    Inspeccionar `.context-map/vault-ContextMap/2.0-IDEAS/2.1-Ideas-Pendientes/` y `5.0-BACKLOG/5.1-Tareas.md`.
 6. **No Suponer Rutas o Lógica**:
    Inspeccionar el código fuente antes de formular hipótesis de cambio.
-7. **Captura Autónoma del Dominio**:
-   Al inicializar o ponerse en contexto en un proyecto, inspeccionar los submódulos de lógica nuclear (algoritmos, ecuaciones implícitas, reglas de negocio) y documentar lo descubierto en `7.0-MANUAL/DOMINIO.md` o en las notas del Vault, ejecutando `ctxmap refresh .` para que el brief y el Vault contengan el alma matemática y funcional del sistema.
+7. **Captura Autónoma del Dominio y Documentación**:
+   Al inicializar o ponerse en contexto en un proyecto, inspeccionar los submódulos de lógica nuclear (algoritmos, ecuaciones implícitas, reglas de negocio) y documentar lo descubierto en `7.0-MANUAL/DOMINIO.md` o en las notas del Vault. Para fuentes documentales externas (.pdf, .md, .txt), depositarlas en `.context-map/raw/docs/` y ejecutar `ctxmap refresh .`.
+8. **Memoria Viva Multicanal**:
+   Todo chat de Antigravity IDE, Hermes o exportación depositada en `.context-map/chats/` se procesa automáticamente en `ctxmap refresh .` para preservar decisiones y evitar pérdida de contexto histórico.
 
 > ⚠️ **NUNCA respondas "¿qué quedó pendiente?" basándote solo en un documento
 > suelto (auditoría, CHANGELOG, docs/)** — cruza SIEMPRE el brief + backlog manual
-> + diario más reciente. Esa es la fuente de verdad del proyecto.
+> + diario más reciente + documentos ingeridos. Esa es la fuente de verdad del proyecto.
 
 ---
 

{context_map_ai-2.3.0 → context_map_ai-2.4.0}/CHANGELOG.md

@@ -5,6 +5,24 @@ Todas las notas de versión y cambios destacables en este proyecto serán docume
 El formato está basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1.0.0/),
 y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.4.0] — 2026-09-23
+
+### 🚀 Evolución Arquitectónica, Modularización, Prompt Caching Determinista & Skills Nativas
+
+- **refactor(`personal`)**: Modularización completa del módulo monolítico `personal.py` (1.054 líneas) en el subpaquete desacoplado `context_map/application/commands/personal/` (`common.py`, `sync.py`, `export.py`, `query.py`, `panorama.py`, `timeline.py`, `repair.py` e `__init__.py`) bajo Clean Architecture y principio de responsabilidad única (SRP), garantizando retrocompatibilidad y soporte dinámico de monkeypatching en tests.
+- **feat(`brief`/`caching`)**: Optimizador determinista de Prompt Caching para Claude 3.7 Sonnet, Gemini 2.5 Pro/Flash y GPT-4o en `CONTEXT.md`. Congela un prefijo invariante estático de 1.005 tokens (identidad, propósito y reglas inmutables) sin marcas de tiempo volátiles al inicio, inyecta el delimitador formal `<!-- PROMPT_CACHE_BOUNDARY: INVARIANT_PREFIX -->` y sitúa el bloque dinámico al final, logrando una tasa de Cache Hit >90%, reducción de latencia de 4s a <500ms y recorte de costos en 90%.
+- **feat(`ecosystem`/`antigravity`)**: Generador nativo de la skill oficial de Antigravity en `.agents/skills/contextmap/SKILL.md` con frontmatter YAML estándar (`name: contextmap`) y directivas de memoria viva, complementado con el flujo declarativo `.hermes/workflows/contextmap.yaml`.
+- **perf(`scanner`)**: Acelerador de escaneo incremental en `infrastructure/analyzers/content.py` con persistencia de caché sintáctica `.context-map/.scan_cache.json` basada en huellas `(mtime_ns, size)`, permitiendo re-escaneos sub-150ms.
+- **ci(`mypy`)**: Saneamiento de 39 inconsistencias de tipado estricto (0 errores en 190 archivos) y promoción de MyPy a verificación 100% bloqueante en `.github/workflows/ci.yml`.
+- **feat(`personal`)**: Nuevo comando `ctxmap personal panorama` para visualización ejecutiva del estado de actividad real de todos los proyectos con semáforo inteligente (`max(max_ts_ses, max_ts_ev)`), conteo de pendientes y directrices activas.
+- **feat(`personal`)**: Nuevo comando `ctxmap personal timeline` para inspección cronológica unificada de sesiones de IA, commits y cambios relevantes con filtros por días, proyecto o tipo de evento.
+- **feat(`personal`)**: Nuevo comando `ctxmap personal repair` para saneamiento automatizado de eventos de ruido técnico, deduplicación/fusión de proyectos duplicados, optimización de índices FTS5 y `VACUUM` de SQLite con respaldo previo `.bak`.
+- **feat(`personal`)**: Exportación del Vault Personal v2 con notas ricas por proyecto, manejo determinista de colisiones de slugs y saneamiento de enlaces para 0 wikilinks rotos.
+- **feat(`memory`/`multichannel`)**: Auto-importación multicanal de memoria viva en `ctxmap refresh .`: integración automática y tolerante de sesiones de Antigravity IDE (`~/.gemini/antigravity-ide/brain/`), exportaciones de chat externas en `.context-map/chats/` y auto-ingesta de documentos de dominio en `.context-map/raw/docs/` (`.md`, `.txt`, `.pdf`) como nodos `DOCUMENTO` en el grafo y Vault (`3.2-DOCUMENTOS/`), garantizando preservación histórica total.
+- **test**: 264/264 pruebas unitarias pasando al 100% con suite de verificación de auto-ingesta multicanal, Prompt Caching y caché de escaneo incremental.
+
+---
+
 ## [2.3.0] — 2026-08-21
 
 ### 🛡️ Novedades y Mejoras — Escáner de Secretos Avanzado, Entropía Shannon, Opt-Out Ollama & Automatización Release

context_map_ai-2.4.0/CLAUDE.md

@@ -0,0 +1,26 @@
+# CLAUDE.md — ContextMap
+
+> Generado automáticamente por **ContextMap** — adaptado al stack real (2026-08-24 12:41).
+
+## Contexto del proyecto
+
+Este proyecto usa **ContextMap** para gobernanza de contexto. Antes de modificar código:
+
+1. Lee `.context-map/CONTEXT.md` (brief ejecutivo: métricas, riesgos, tareas).
+2. Explora el vault en `.context-map/vault-ContextMap/` para entender el grafo del proyecto.
+3. No supongas lógica: inspecciona el código fuente antes de proponer cambios.
+4. Para contexto histórico global (otros proyectos): `ctxmap personal query "términos" --limite 5` (BD personal FTS5, pocos tokens).
+
+## Comandos de verificación
+
+```bash
+python -m pytest
+python -m context_map.cli build --clean --brief
+python -m context_map.cli check .
+```
+
+## Convenciones
+
+- Commits: Conventional Commits en español (`feat:`, `fix:`, `refactor:`, `docs:`).
+- Respuestas y docstrings en Español Técnico Profesional.
+- Respetar la arquitectura modular existente; no crear archivos sueltos en la raíz.

context_map_ai-2.4.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.5
+Name: context-map-ai
+Version: 2.4.0
+Summary: ContextMap IA — Memoria permanente y mapa mental narrativo para agentes de IA
+Project-URL: Homepage, https://github.com/kudawasama/ContextMap
+Project-URL: Repository, https://github.com/kudawasama/ContextMap
+Project-URL: Issues, https://github.com/kudawasama/ContextMap/issues
+Author-email: kudawasama <cespedes.jac@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,context,mindmap,obsidian
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Spanish
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: isort>=5.13.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2.0.0,>=1.2.0; extra == 'mcp'
+Requires-Dist: pydantic<3,>=2.13; extra == 'mcp'
+Provides-Extra: pdf
+Requires-Dist: pymupdf>=1.24.0; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# 🗺️ ContextMap
+
+<div align="center">
+
+# La Memoria Permanente para tus Asistentes de IA
+
+### *Evita que tu IA olvide tus decisiones, gaste dinero en tokens y rompa tu código.*
+
+[![Release](https://img.shields.io/badge/version-v2.4.0-blue.svg?style=for-the-badge)](CHANGELOG.md)
+[![PyPI](https://img.shields.io/pypi/v/context-map-ai.svg?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/context-map-ai/)
+[![Python](https://img.shields.io/badge/python-3.10+-3776AB.svg?style=for-the-badge&logo=python&logoColor=white)](pyproject.toml)
+[![Tests: 264 Passing](https://img.shields.io/badge/tests-264%2F264%20passing-brightgreen.svg?style=for-the-badge)](context_map/__tests__/)
+[![Type Check: Strict MyPy](https://img.shields.io/badge/mypy-100%25%20strict-00599C.svg?style=for-the-badge&logo=python&logoColor=white)](.github/workflows/ci.yml)
+[![Prompt Cache: Optimized](https://img.shields.io/badge/Prompt%20Cache->90%25%20Hit%20Rate-orange.svg?style=for-the-badge)](context_map/presentation/briefs/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](LICENSE)
+
+[English Version 🇬🇧](README_EN.md) • [📖 Documentación Técnica y Arquitectura 🏛️](README_TECNICO.md) • [Historial de Versiones](CHANGELOG.md)
+
+</div>
+
+---
+
+## 😫 El Gran Problema al Programar con Inteligencia Artificial
+
+Si usas **Cursor, Claude, Copilot, ChatGPT, Antigravity o Windsurf**, seguro te ha pasado esto:
+
+1. 🧠 **Amnesia Constante**: Abres un nuevo chat y la IA olvidó todo lo que conversaron ayer. Tienes que volver a explicarle el proyecto desde cero.
+2. 💸 **Desperdicio de Tokens y Dinero**: Copiar y pegar 100 archivos en cada pregunta satura el límite de contexto, cuesta caro y confunde al modelo.
+3. 💥 **Refactorizaciones a Ciegas**: La IA cambia código que ya funcionaba porque desconoce las decisiones pasadas y las reglas de negocio.
+4. 🔒 **Vendor Lock-in**: Si cambias de editor (de Cursor a Claude o a VS Code), pierdes todo el contexto acumulado.
+
+---
+
+## 💡 La Solución: ContextMap
+
+**ContextMap es como darle un "disco duro de memoria viva" a tus IAs.**
+
+Escanea tu proyecto, entiende su estructura y propósito, y genera dos cosas mágicas:
+1. 🗺️ **Un Mapa Mental Visual en Obsidian**: Una bóveda interactiva hermosa donde puedes ver en tiempo real cómo se conectan las ideas, módulos, riesgos y decisiones.
+2. 📄 **Un Brief Ejecutivo Ultra-Compacto (`CONTEXT.md`)**: Un resumen de alta densidad de solo **~1.600 tokens** que le enseña al instante a cualquier IA todo lo que necesita saber sin saturar su memoria (**>99% de ahorro de tokens**).
+
+```
+   ┌───────────────────────────────────────────────────────────────┐
+   │                   TU PROYECTO DE SOFTWARE                     │
+   └───────────────────────────────┬───────────────────────────────┘
+                                   │
+                           [ ctxmap refresh ]
+                                   │
+                 ┌─────────────────┴─────────────────┐
+                 ▼                                   ▼
+        🗺️ BÓVEDA OBSIDIAN                  📄 BRIEF EJECUTIVO
+     (Visual, Interactiva,              (Solo ~1.600 tokens,
+      Conexiones y Grafos)               Ahorro >99% en LLMs)
+                 │                                   │
+                 └─────────────────┬─────────────────┘
+                                   ▼
+          🤖 COMPATIBLE CON CUALQUIER ASISTENTE DE IA
+        Cursor · Claude Code · Copilot · Antigravity · Hermes
+```
+
+---
+
+## 🚀 Inicio Rápido en 3 Pasos
+
+### 1. Instálalo en 1 comando
+```bash
+pip install context-map-ai
+```
+*(O con `uv`: `uv tool install context-map-ai`)*
+
+### 2. Inicializa tu proyecto
+Dentro de la carpeta de tu proyecto, dile a tu IA en el chat:
+> 💬 *"Inicializa ContextMap para este proyecto"*
+
+O ejecútalo tú mismo en la terminal:
+```bash
+ctxmap auto .
+```
+
+### 3. ¡Listo! Mantén el contexto al día tras hacer cambios
+Cada vez que avances en tu código o tomes acuerdos importantes:
+```bash
+ctxmap refresh .
+```
+
+---
+
+## ✨ ¿Por Qué ContextMap Enamora a los Desarrolladores?
+
+### 🧠 1. Memoria Indestructible (`7.0-MANUAL/`)
+¿Tomaste una decisión crítica con el cliente o tu equipo? Anótala en tu diario o notas manuales. El motor de ContextMap **jamás borrará tus notas** (`preserve: true`). La IA recordará ese acuerdo para siempre.
+
+### 🌐 2. Tablero de Control Multi-Proyecto (`ctxmap personal panorama`)
+¿Trabajas en 5, 10 o 20 proyectos a la vez? Con un solo comando tienes un semáforo visual de qué proyectos están activos, cuáles dormidos y qué tareas urgentes tienen pendientes:
+
+```text
+============================================================================
+🌐 PANORAMA MULTI-PROYECTO
+============================================================================
+Proyecto               Semáforo   Inactivo   Eventos  Lecc/Dec   Sesiones
+----------------------------------------------------------------------------
+Mi-Tienda-Online       🟢 Activo   1d         582      4/2        3       
+App-Finanzas           🟢 Activo   5d         336      4/0        1       
+Bot-Automatizacion     🟡 Tibio    21d        32       2/1        0       
+----------------------------------------------------------------------------
+```
+
+### 🔌 3. Control Directo para Agentes de IA (Servidor MCP Nativo & Skills)
+ContextMap incluye un servidor **MCP nativo (16 herramientas)** y generador de **Skills para Antigravity**. Asistentes como **Antigravity, Hermes Agent, Claude Desktop, Cursor o Windsurf** pueden sincronizar el mapa, consultar lecciones y registrar decisiones de forma completamente autónoma sin que toques la terminal.
+
+### 🛡️ 4. Reglas y Skills Universales para 10+ Editores e IAs
+Escribe tus normas una sola vez y ContextMap las inyecta en el formato nativo de cada herramienta:
+* **Google Antigravity**: `.agents/skills/contextmap/SKILL.md`
+* **Hermes Agent**: `.hermes/workflows/contextmap.yaml` y `.hermes/config.yaml`
+* **Universal**: `AGENTS.md`
+* **Claude Code**: `CLAUDE.md`
+* **Cursor**: `.cursor/rules/contextmap.mdc` y `.cursorrules`
+* **GitHub Copilot**: `.github/copilot-instructions.md`
+* **Windsurf**: `.windsurfrules`
+* **Cline / Roo Code**: `.clinerules`
+
+---
+
+## ⚖️ Comparativa: ContextMap vs. Otras Soluciones
+
+| ¿Qué necesitas? | Copiar y Pegar Todo<br>*(Repomix / Gitingest)* | Indexadores de Editor<br>*(Cursor / Windsurf)* | **ContextMap v2.4.0** |
+| :--- | :---: | :---: | :---: |
+| **Gasto de Tokens** | 🔴 Altísimo (quema tu dinero) | 🟡 Medio | 🟢 **Mínimo (>99% de ahorro)** |
+| **Prompt Caching Determinista** | ❌ Incompatible (cambia el hash) | 🟡 Parcial | **✅ Prefijo congelado (>90% Hit Rate)** |
+| **Mapa Visual Interactivo** | ❌ No existe | ❌ No existe | **✅ Bóveda en Obsidian** |
+| **No Olvidar Acuerdos** | ❌ Pierde todo al cerrar chat | 🟡 Parcial | **✅ Memoria Permanente** |
+| **Cambiar de Editor sin Perder Datos** | ❌ No | ❌ Atrapado en su app | **✅ Totalmente Portable** |
+| **Visión de Múltiples Proyectos** | ❌ No | ❌ No | **✅ Base SQLite Consolidada** |
+| **Herramientas MCP & Skills Nativas** | ❌ No | 🟡 Cerradas | **✅ 16 Tools stdio + Antigravity Skill** |
+
+---
+
+## 💻 Comandos Principales
+
+```bash
+# 🚀 Día a día: sincroniza y actualiza todo el contexto
+ctxmap refresh .
+
+# 🌐 Vista global: semáforo de todos tus proyectos
+ctxmap personal panorama
+
+# ⏱️ Línea de tiempo: qué se trabajó en los últimos días
+ctxmap personal timeline --dias 7
+
+# 🔍 Búsqueda ultra-rápida: consulta lecciones y decisiones pasadas
+ctxmap personal query "autenticación jwt"
+
+# 🏥 Diagnóstico: revisa la salud de tu contexto
+ctxmap check .
+```
+
+---
+
+## 📚 Documentación Técnica Avanzada
+
+Si eres arquitecto de software o desarrollador y quieres conocer los detalles de bajo nivel (inspección AST de Python, cálculo de Complejidad Ciclomática de McCabe, Entropía de Shannon para escaneo de secretos, protocolo MCP stdio y topología acíclica de grafos):
+
+👉 **[Consulta la Documentación Técnica y de Arquitectura (README_TECNICO.md)](README_TECNICO.md)**
+
+---
+
+## 📄 Licencia
+
+Este proyecto está liberado bajo la Licencia **MIT**. Eres libre de usarlo, modificarlo e integrarlo en proyectos personales o comerciales.

context_map_ai-2.4.0/README.md

@@ -0,0 +1,169 @@
+# 🗺️ ContextMap
+
+<div align="center">
+
+# La Memoria Permanente para tus Asistentes de IA
+
+### *Evita que tu IA olvide tus decisiones, gaste dinero en tokens y rompa tu código.*
+
+[![Release](https://img.shields.io/badge/version-v2.4.0-blue.svg?style=for-the-badge)](CHANGELOG.md)
+[![PyPI](https://img.shields.io/pypi/v/context-map-ai.svg?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/context-map-ai/)
+[![Python](https://img.shields.io/badge/python-3.10+-3776AB.svg?style=for-the-badge&logo=python&logoColor=white)](pyproject.toml)
+[![Tests: 264 Passing](https://img.shields.io/badge/tests-264%2F264%20passing-brightgreen.svg?style=for-the-badge)](context_map/__tests__/)
+[![Type Check: Strict MyPy](https://img.shields.io/badge/mypy-100%25%20strict-00599C.svg?style=for-the-badge&logo=python&logoColor=white)](.github/workflows/ci.yml)
+[![Prompt Cache: Optimized](https://img.shields.io/badge/Prompt%20Cache->90%25%20Hit%20Rate-orange.svg?style=for-the-badge)](context_map/presentation/briefs/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](LICENSE)
+
+[English Version 🇬🇧](README_EN.md) • [📖 Documentación Técnica y Arquitectura 🏛️](README_TECNICO.md) • [Historial de Versiones](CHANGELOG.md)
+
+</div>
+
+---
+
+## 😫 El Gran Problema al Programar con Inteligencia Artificial
+
+Si usas **Cursor, Claude, Copilot, ChatGPT, Antigravity o Windsurf**, seguro te ha pasado esto:
+
+1. 🧠 **Amnesia Constante**: Abres un nuevo chat y la IA olvidó todo lo que conversaron ayer. Tienes que volver a explicarle el proyecto desde cero.
+2. 💸 **Desperdicio de Tokens y Dinero**: Copiar y pegar 100 archivos en cada pregunta satura el límite de contexto, cuesta caro y confunde al modelo.
+3. 💥 **Refactorizaciones a Ciegas**: La IA cambia código que ya funcionaba porque desconoce las decisiones pasadas y las reglas de negocio.
+4. 🔒 **Vendor Lock-in**: Si cambias de editor (de Cursor a Claude o a VS Code), pierdes todo el contexto acumulado.
+
+---
+
+## 💡 La Solución: ContextMap
+
+**ContextMap es como darle un "disco duro de memoria viva" a tus IAs.**
+
+Escanea tu proyecto, entiende su estructura y propósito, y genera dos cosas mágicas:
+1. 🗺️ **Un Mapa Mental Visual en Obsidian**: Una bóveda interactiva hermosa donde puedes ver en tiempo real cómo se conectan las ideas, módulos, riesgos y decisiones.
+2. 📄 **Un Brief Ejecutivo Ultra-Compacto (`CONTEXT.md`)**: Un resumen de alta densidad de solo **~1.600 tokens** que le enseña al instante a cualquier IA todo lo que necesita saber sin saturar su memoria (**>99% de ahorro de tokens**).
+
+```
+   ┌───────────────────────────────────────────────────────────────┐
+   │                   TU PROYECTO DE SOFTWARE                     │
+   └───────────────────────────────┬───────────────────────────────┘
+                                   │
+                           [ ctxmap refresh ]
+                                   │
+                 ┌─────────────────┴─────────────────┐
+                 ▼                                   ▼
+        🗺️ BÓVEDA OBSIDIAN                  📄 BRIEF EJECUTIVO
+     (Visual, Interactiva,              (Solo ~1.600 tokens,
+      Conexiones y Grafos)               Ahorro >99% en LLMs)
+                 │                                   │
+                 └─────────────────┬─────────────────┘
+                                   ▼
+          🤖 COMPATIBLE CON CUALQUIER ASISTENTE DE IA
+        Cursor · Claude Code · Copilot · Antigravity · Hermes
+```
+
+---
+
+## 🚀 Inicio Rápido en 3 Pasos
+
+### 1. Instálalo en 1 comando
+```bash
+pip install context-map-ai
+```
+*(O con `uv`: `uv tool install context-map-ai`)*
+
+### 2. Inicializa tu proyecto
+Dentro de la carpeta de tu proyecto, dile a tu IA en el chat:
+> 💬 *"Inicializa ContextMap para este proyecto"*
+
+O ejecútalo tú mismo en la terminal:
+```bash
+ctxmap auto .
+```
+
+### 3. ¡Listo! Mantén el contexto al día tras hacer cambios
+Cada vez que avances en tu código o tomes acuerdos importantes:
+```bash
+ctxmap refresh .
+```
+
+---
+
+## ✨ ¿Por Qué ContextMap Enamora a los Desarrolladores?
+
+### 🧠 1. Memoria Indestructible (`7.0-MANUAL/`)
+¿Tomaste una decisión crítica con el cliente o tu equipo? Anótala en tu diario o notas manuales. El motor de ContextMap **jamás borrará tus notas** (`preserve: true`). La IA recordará ese acuerdo para siempre.
+
+### 🌐 2. Tablero de Control Multi-Proyecto (`ctxmap personal panorama`)
+¿Trabajas en 5, 10 o 20 proyectos a la vez? Con un solo comando tienes un semáforo visual de qué proyectos están activos, cuáles dormidos y qué tareas urgentes tienen pendientes:
+
+```text
+============================================================================
+🌐 PANORAMA MULTI-PROYECTO
+============================================================================
+Proyecto               Semáforo   Inactivo   Eventos  Lecc/Dec   Sesiones
+----------------------------------------------------------------------------
+Mi-Tienda-Online       🟢 Activo   1d         582      4/2        3       
+App-Finanzas           🟢 Activo   5d         336      4/0        1       
+Bot-Automatizacion     🟡 Tibio    21d        32       2/1        0       
+----------------------------------------------------------------------------
+```
+
+### 🔌 3. Control Directo para Agentes de IA (Servidor MCP Nativo & Skills)
+ContextMap incluye un servidor **MCP nativo (16 herramientas)** y generador de **Skills para Antigravity**. Asistentes como **Antigravity, Hermes Agent, Claude Desktop, Cursor o Windsurf** pueden sincronizar el mapa, consultar lecciones y registrar decisiones de forma completamente autónoma sin que toques la terminal.
+
+### 🛡️ 4. Reglas y Skills Universales para 10+ Editores e IAs
+Escribe tus normas una sola vez y ContextMap las inyecta en el formato nativo de cada herramienta:
+* **Google Antigravity**: `.agents/skills/contextmap/SKILL.md`
+* **Hermes Agent**: `.hermes/workflows/contextmap.yaml` y `.hermes/config.yaml`
+* **Universal**: `AGENTS.md`
+* **Claude Code**: `CLAUDE.md`
+* **Cursor**: `.cursor/rules/contextmap.mdc` y `.cursorrules`
+* **GitHub Copilot**: `.github/copilot-instructions.md`
+* **Windsurf**: `.windsurfrules`
+* **Cline / Roo Code**: `.clinerules`
+
+---
+
+## ⚖️ Comparativa: ContextMap vs. Otras Soluciones
+
+| ¿Qué necesitas? | Copiar y Pegar Todo<br>*(Repomix / Gitingest)* | Indexadores de Editor<br>*(Cursor / Windsurf)* | **ContextMap v2.4.0** |
+| :--- | :---: | :---: | :---: |
+| **Gasto de Tokens** | 🔴 Altísimo (quema tu dinero) | 🟡 Medio | 🟢 **Mínimo (>99% de ahorro)** |
+| **Prompt Caching Determinista** | ❌ Incompatible (cambia el hash) | 🟡 Parcial | **✅ Prefijo congelado (>90% Hit Rate)** |
+| **Mapa Visual Interactivo** | ❌ No existe | ❌ No existe | **✅ Bóveda en Obsidian** |
+| **No Olvidar Acuerdos** | ❌ Pierde todo al cerrar chat | 🟡 Parcial | **✅ Memoria Permanente** |
+| **Cambiar de Editor sin Perder Datos** | ❌ No | ❌ Atrapado en su app | **✅ Totalmente Portable** |
+| **Visión de Múltiples Proyectos** | ❌ No | ❌ No | **✅ Base SQLite Consolidada** |
+| **Herramientas MCP & Skills Nativas** | ❌ No | 🟡 Cerradas | **✅ 16 Tools stdio + Antigravity Skill** |
+
+---
+
+## 💻 Comandos Principales
+
+```bash
+# 🚀 Día a día: sincroniza y actualiza todo el contexto
+ctxmap refresh .
+
+# 🌐 Vista global: semáforo de todos tus proyectos
+ctxmap personal panorama
+
+# ⏱️ Línea de tiempo: qué se trabajó en los últimos días
+ctxmap personal timeline --dias 7
+
+# 🔍 Búsqueda ultra-rápida: consulta lecciones y decisiones pasadas
+ctxmap personal query "autenticación jwt"
+
+# 🏥 Diagnóstico: revisa la salud de tu contexto
+ctxmap check .
+```
+
+---
+
+## 📚 Documentación Técnica Avanzada
+
+Si eres arquitecto de software o desarrollador y quieres conocer los detalles de bajo nivel (inspección AST de Python, cálculo de Complejidad Ciclomática de McCabe, Entropía de Shannon para escaneo de secretos, protocolo MCP stdio y topología acíclica de grafos):
+
+👉 **[Consulta la Documentación Técnica y de Arquitectura (README_TECNICO.md)](README_TECNICO.md)**
+
+---
+
+## 📄 Licencia
+
+Este proyecto está liberado bajo la Licencia **MIT**. Eres libre de usarlo, modificarlo e integrarlo en proyectos personales o comerciales.