diff --git a/README.md b/README.md index b246af5..14b975c 100644 --- a/README.md +++ b/README.md @@ -25,31 +25,46 @@ The static output is written to `build/` and can be served from any static host. The docs site is deployed on Vercel at [https://ghostmap-docs.vercel.app/](https://ghostmap-docs.vercel.app/). Vercel builds from this repository's default branch using the standard Docusaurus build (`npm run build`, output in `build/`); see `docusaurus.config.js` for site configuration. Publish the marketing site after a docs deploy completes, because the marketing site links to the rendered docs routes. +## Languages + +The root docs experience starts in English. Spanish has the detailed reference pages: + +- **English**: root start page plus short pages under `docs/en/`: overview, + install/access, and legal/support. +- **Spanish**: detailed pages: requisitos, instalación, conceptos, sintaxis, + referencia de settings, arquitectura, estado del proyecto, roadmap. +- **Legal documents (English-authoritative)**: `docs/legal/*` and the + shipped `LICENSE` / `THIRD_PARTY_NOTICES.txt` are in English as the + canonical legal version. The Spanish docs reference them, they are not + re-translated. + ## Content structure | Folder | Purpose | |---|---| -| `docs/intro.md` | Landing page of the documentation. | -| `docs/get-started/` | Requisitos, instalación, primeros 5 minutos. | -| `docs/guide/` | Conceptos: symbols, anchors, ownership, validity gate, etc. | -| `docs/reference/` | Syntax, Ghost Tree, diagnostics, settings, rendimiento. | -| `docs/architecture/` | Arquitectura v1, loading policy, local state. | -| `docs/roadmap/` | Visión v2 (Ghost Index v2, Ghost Watcher, Ghost Comments, Ghost Threads, Ghost Graph). | -| `docs/status/` | Estado del proyecto y limitaciones conocidas. | +| `docs/intro.md` | English root start page. | +| `docs/en/` | English overview, install/access, legal & support summary. | +| `docs/get-started/` | Requisitos, instalación, primeros 5 minutos (ES). | +| `docs/guide/` | Conceptos: symbols, anchors, ownership, validity gate, etc. (ES). | +| `docs/reference/` | Syntax, Ghost Tree, diagnostics, settings, rendimiento (ES). | +| `docs/architecture/` | Arquitectura v1, loading policy, local state (ES). | +| `docs/roadmap/` | Visión v2 (ES). | +| `docs/status/` | Estado del proyecto y limitaciones conocidas (ES). | | `docs/changelog.md` | User-visible release notes. | -| `docs/legal/` | Privacy Policy, Terms of Use, Third-Party Notices, Disclaimer. | -| `sidebars.js` | Sidebar layout. | -| `docusaurus.config.js` | Site configuration. | +| `docs/legal/` | Privacy Policy, Terms of Use, Third-Party Notices, Disclaimer (English-authoritative). | +| `sidebars.js` | Sidebar layout (English start first, then Spanish details). | +| `docusaurus.config.js` | Site configuration (English default locale, navbar, and footer). | ## Contributing to the docs -The docs are currently written in Spanish. The legal section and the changelog are in English (since they need to be canonical). A full English translation is on the roadmap. +English pages are short start pages. Spanish pages hold the detailed product +docs. The legal section and changelog are English-authoritative. To add a new page: 1. Create the `.md` file under the appropriate `docs//` folder with a YAML frontmatter block (`id`, `title`, `sidebar_label`). 2. Add the page id to `sidebars.js` under the right category. -3. Run `npm start` to verify the page renders and links resolve. +3. Run `npm run build` to verify the page renders and links resolve. 4. Open a pull request. ## Related surfaces diff --git a/docs/architecture/arquitectura-v1.md b/docs/architecture/arquitectura-v1.md index 2a87faa..4745076 100644 --- a/docs/architecture/arquitectura-v1.md +++ b/docs/architecture/arquitectura-v1.md @@ -6,9 +6,8 @@ sidebar_label: Arquitectura v1 # Arquitectura actual (v1 / MVP) -:::info -Esta sección es para devs curiosos y colaboradores. No es necesaria para el uso diario de GhostMap. -::: +> **Nota:** +> Esta sección es para devs curiosos y colaboradores. No es necesaria para el uso diario de GhostMap. ## Diagrama de flujo @@ -36,7 +35,7 @@ Este pipeline completo se ejecuta: - Al abrir o activar un editor. - En cada edición, con un pequeño retraso (debounce) para no recalcular en cada tecla. -En V1, no hay persistencia completa entre sesiones a nivel de workspace — cada apertura de archivo repite el cálculo. La excepción es la caché de continuidad por documento descrita en [Local State](/architecture/local-state). El [roadmap v2](/roadmap/vision-v2) plantea eliminar este recálculo por completo con un índice persistente de workspace. +En V1, no hay persistencia completa entre sesiones a nivel de workspace: cada apertura de archivo repite el cálculo. La excepción es la caché de continuidad por documento descrita en [Local State](/architecture/local-state). El [roadmap v2](/roadmap/vision-v2) plantea eliminar este recálculo por completo con un índice persistente de workspace. ## Modelo de datos (`GhostItem`) diff --git a/docs/architecture/loading-policy.md b/docs/architecture/loading-policy.md index 05bdada..4f7a4d0 100644 --- a/docs/architecture/loading-policy.md +++ b/docs/architecture/loading-policy.md @@ -13,7 +13,7 @@ Sin límites, abrir un archivo enorme (decenas o cientos de miles de líneas) di ## Comportamiento - Existe un presupuesto por defecto: `ghostmap.loading.maxAutoLines = 60000` (60,000 líneas). -- Si un archivo supera ese presupuesto, el **refresco automático** (al abrir o editar) se omite por defecto — no se ejecuta un análisis "fresco". +- Si un archivo supera ese presupuesto, el **refresco automático** (al abrir o editar) se omite por defecto: no se ejecuta un análisis "fresco". - Si existe un **snapshot previo válido** en el [Local State](/architecture/local-state), ese snapshot puede seguir mostrándose (UI "cacheada/stale") aunque no se recalcule. - El **refresco manual** (botón `Refresh`) sobre un archivo que excede el presupuesto **también se omite por defecto**, a menos que habilites explícitamente `ghostmap.loading.allowManualLargeFileRefresh = true`. @@ -21,9 +21,8 @@ Sin límites, abrir un archivo enorme (decenas o cientos de miles de líneas) di > "Este archivo tiene más de 60,000 líneas. GhostMap no recalculó el árbol automáticamente para evitar bloquear el editor. Si el árbol mostrado se ve desactualizado, puedes habilitar `ghostmap.loading.allowManualLargeFileRefresh` y usar `Refresh` manualmente." -:::tip Relación con v2 -El [Ghost Index v2](/roadmap/vision-v2) apunta a reducir este límite con un índice persistente y actualización incremental, para evitar recalcular archivos completos al abrirlos. Incluso en V2 seguirán haciendo falta presupuestos, backpressure y pruebas de recuperación para proteger el Extension Host en archivos extremos. -::: +> **Relación con v2:** +> El [Ghost Index v2](/roadmap/vision-v2) apunta a reducir este límite con un índice persistente y actualización incremental, para evitar recalcular archivos completos al abrirlos. Incluso en V2 seguirán haciendo falta presupuestos, backpressure y pruebas de recuperación para proteger el Extension Host en archivos extremos. ## Siguiente paso diff --git a/docs/architecture/local-state.md b/docs/architecture/local-state.md index 14bf435..f41d3bb 100644 --- a/docs/architecture/local-state.md +++ b/docs/architecture/local-state.md @@ -10,14 +10,14 @@ sidebar_label: Local State Una caché local por workspace que GhostMap mantiene en V1, guardada en `.ghostmap/ghostmap.json` dentro del proyecto. GhostMap recuerda el estado de tus archivos entre sesiones para cargar más rápido. -Es un primer paso —más simple— hacia lo que el [roadmap v2](/roadmap/vision-v2) llama "Ghost Project Index": en V1 es una caché de continuidad por archivo/documento; en v2 se plantea como un índice completo de workspace con relaciones, watcher incremental y analítica. +Es un primer paso (más simple) hacia lo que el [roadmap v2](/roadmap/vision-v2) llama "Ghost Project Index": en V1 es una caché de continuidad por archivo/documento; en v2 se plantea como un índice completo de workspace con relaciones, watcher incremental y analítica. ## Comportamiento - Al cerrar y reabrir un documento, GhostMap puede restaurar el último estado conocido (`ghostmap.json`) en lugar de recalcular desde cero inmediatamente. -- **Regla de seguridad:** si los datos restaurados son "stale" (no se ha confirmado que sigan siendo válidos), no se publican como frescos en hover ni en navegación — la UI puede mostrar algo provisional, pero GhostMap no afirma que esa información está al día hasta confirmarlo. -- Casos manejados de forma defensiva: JSON corrupto y esquemas no soportados de versiones anteriores del archivo — en ambos casos, GhostMap no falla ni muestra datos incorrectos como válidos. +- **Regla de seguridad:** si los datos restaurados son "stale" (no se ha confirmado que sigan siendo válidos), no se publican como frescos en hover ni en navegación: la UI puede mostrar algo provisional, pero GhostMap no afirma que esa información está al día hasta confirmarlo. +- Casos manejados de forma defensiva: JSON corrupto y esquemas no soportados de versiones anteriores del archivo: en ambos casos, GhostMap no falla ni muestra datos incorrectos como válidos. ## Siguiente paso -Con esto termina la sección de Arquitectura. Si quieres saber qué viene después, continúa con **[Roadmap — Visión v2](/roadmap/vision-v2)**. +Con esto termina la sección de Arquitectura. Si quieres saber qué viene después, continúa con **[Roadmap: Visión v2](/roadmap/vision-v2)**. diff --git a/docs/en/install.md b/docs/en/install.md new file mode 100644 index 0000000..506de95 --- /dev/null +++ b/docs/en/install.md @@ -0,0 +1,59 @@ +--- +title: Install & Access (English) +sidebar_label: Install / Access (EN) +slug: /en/install +--- + +# Install & Access: English quick-start + +> **English start page.** For more detail, see [Instalación (ES)](/get-started/instalacion). + +## Current install reality + +GhostMap is not yet published on the VS Code Marketplace or Open VSX. The +current way to install it is a **locally-built VSIX**, distributed on request. + +### Request a VSIX + +Send an email to [getghostmap@proton.me](mailto:getghostmap@proton.me?subject=GhostMap%20VSIX%20request) +describing your use case. You will receive the same `.vsix` binary the +extension repository produces. + +### Install it + +Once you have the `.vsix` file: + +```powershell +code --install-extension ghostmap-0.5.0.vsix +``` + +Or, in VS Code: `Extensions` panel → `…` menu → `Install from VSIX…` → +select the file. + +After install: + +1. Open a file in any supported language (TypeScript, Python, Rust, C#, Java, + PHP, C++, Go, Ruby, Dart, etc.: 19 in total). +2. Open the **GhostMap** view in the activity bar. +3. The tree shows every detected symbol; click an item to jump. +4. Drop a `@ghost` anchor in a comment: it appears in the tree. + +## Planned channels (not active today) + +| Channel | Status | Notes | +| --- | --- | --- | +| Local VSIX on request | Active | Email `getghostmap@proton.me`. | +| GitHub Releases | Planned, post-tag | No public tagged release exists yet. | +| VS Code Marketplace | Planned | Depends on publisher onboarding. No fake link is published anywhere. | +| Open VSX | Planned | Bridge for VSCodium and Open VSX-compatible editors; needs a namespace + token. | + +When a channel becomes active, the link will appear here and on the docs +landing page. The project does not publish placeholder Marketplace, Open VSX, +Lemon Squeezy, Patreon, or Ko-fi links that do not resolve. + +## See also + +- [Spanish install guide (detailed)](/get-started/instalacion). +- [VSIX install reference](/vsix-install). +- [Requirements](/get-started/requisitos). +- [First 5 minutes (ES)](/get-started/primeros-5-minutos). diff --git a/docs/en/legal-support.md b/docs/en/legal-support.md new file mode 100644 index 0000000..e9d3546 --- /dev/null +++ b/docs/en/legal-support.md @@ -0,0 +1,74 @@ +--- +title: Legal & Support (English summary) +sidebar_label: Legal & Support (EN) +slug: /en/legal-support +--- + +# Legal & Support: English summary + +> **Legal documents are authoritative in English.** This page points English +> readers to the legal and support pages. The `LICENSE`, +> `THIRD_PARTY_NOTICES.txt`, Privacy Policy, Terms of Use, and Disclaimer files +> shipped with the extension and rendered in the docs site govern actual use. + +## License (summary) + +GhostMap is owned by the GhostMap project owner / MarxWellB and is +source-available under the **GhostMap Free Non-Commercial License**. + +- **Free for:** personal, educational, evaluation and testing, and other + non-commercial use. +- **Requires written authorization for:** company, business, production, + revenue-generating, client, resale, white-label, marketplace-republish, + and competing-product use. +- **Commercial licensing & legal contact:** [getghostmap@proton.me](mailto:getghostmap@proton.me). + +Voluntary donations and supporter contributions are separate from commercial +authorization and do not grant commercial, company, or production rights. +Supporter benefits are not pricing tiers and do not transfer license rights. + +## Legal documents + +| Document | Where to read it | +| --- | --- | +| Full license text | The `LICENSE` file shipped inside the VSIX. The legal section also summarizes the [Terms of Use](/legal/terms), [Privacy Policy](/legal/privacy), and [Third-Party Notices](/legal/notices). | +| Privacy Policy | [/legal/privacy](/legal/privacy) | +| Terms of Use | [/legal/terms](/legal/terms) | +| Third-Party Notices | [/legal/notices](/legal/notices) | +| Disclaimer | [/legal/disclaimer](/legal/disclaimer) | + +The legal pages themselves are written in English as the canonical version. +The Spanish docs reference them but do not redefine them. + +## Third-party components + +GhostMap bundles `web-tree-sitter` and 19 Tree-sitter grammars. Each component +keeps its own upstream license. The exact upstream `LICENSE` and `SOURCE.txt` +files for every bundled grammar ship inside the extension, under +`wasm/licenses/`, and are mirrored in the `THIRD_PARTY_NOTICES.txt` file in the +VSIX. + +## Support + +There is one support channel today: +[getghostmap@proton.me](mailto:getghostmap@proton.me). + +Use this address for: + +- Requesting a VSIX (see [Install / Access (EN)](/en/install)). +- Bug reports and troubleshooting. +- Commercial licensing inquiries. +- Partnership and integration questions. + +### Voluntary support platforms + +Voluntary supporter platforms (for example Lemon Squeezy, Patreon, Ko-fi) are +**not active today**. They may be adopted later as voluntary processors. When a +platform becomes active, the link will appear here and on the docs site. The +project does not publish placeholder URLs that do not resolve. + +## Spanish docs + +The legal pages live under [/legal/](/legal/privacy) and are authoritative in +English. Spanish project status, support and known limits are at +[Estado del proyecto (ES)](/status/estado-del-proyecto). diff --git a/docs/en/overview.md b/docs/en/overview.md new file mode 100644 index 0000000..9cde4d1 --- /dev/null +++ b/docs/en/overview.md @@ -0,0 +1,72 @@ +--- +title: GhostMap (English overview) +sidebar_label: Overview (EN) +slug: /en/overview +--- + +# GhostMap: English overview + +> The docs root is English-first. These are short English start pages; Spanish +> pages hold the detailed reference. + +## What GhostMap is + +GhostMap is a VS Code extension that turns structured `@ghost` comments into a +navigable map of your file: a semantic tree of classes, functions, methods, +interfaces and anchors that live next to the code they describe. + +You write a comment like: + +```ts +class AuthService { + // @ghost description: review security | status: todo + login() { + // ... + } +} +``` + +GhostMap renders it in the side panel as: + +```text +AuthService +└── login (todo): review security +``` + +No external task tracker, no extra config. The tree rebuilds itself as you type. + +## Where to go next (English) + +- [Start](/): default docs entry. +- [Install / Access (EN)](/en/install): current install reality (local VSIX), planned channels. +- [Legal & Support (EN)](/en/legal-support): license summary, third-party notices, contact. + +## Spanish documentation + +The detailed reference, architecture, and concepts documentation is in Spanish: + +- [Instalación (ES)](/get-started/instalacion): VSIX install guide. +- [Requisitos (ES)](/get-started/requisitos): supported editors and languages. +- [Primeros 5 minutos (ES)](/get-started/primeros-5-minutos): first `@ghost` walkthrough. +- [Conceptos / Guía (ES)](/guide/philosophy): symbols, anchors, ownership radius. +- [Sintaxis (ES)](/reference/sintaxis): full `@ghost` syntax reference. +- [Settings (ES)](/reference/settings): every `ghostmap.*` setting. +- [Arquitectura v1 (ES)](/architecture/arquitectura-v1): internals. +- [Estado del proyecto (ES)](/status/estado-del-proyecto): known limits. +- [Roadmap V2 (ES)](/roadmap/vision-v2): direction. + +## Project status (short) + +- Version 0.5.0, pre-release. +- VS Code engine `^1.85.0`. +- 19 languages supported across quality tiers. +- Distribution today: locally-built VSIX, requested by email. +- Planned channels: GitHub Releases (post-tag), VS Code Marketplace, Open VSX. + None of these are active yet: see [Install / Access (EN)](/en/install). + +## License (short) + +GhostMap is source-available under the **GhostMap Free Non-Commercial License**. +Personal, educational, and evaluation use is free. Commercial use needs a +written license. The English `LICENSE` file shipped with the extension is the +authoritative legal document. See [Legal & Support (EN)](/en/legal-support). diff --git a/docs/faq.md b/docs/faq.md index d6a4f0c..a675fdb 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -10,9 +10,9 @@ sidebar_label: FAQ La vista Outline nativa de VS Code muestra los símbolos del archivo activo según el language server, sin más. GhostMap añade: -- **Fallback automático** cuando el language server no responde o no está disponible, usando Tree-sitter y regex. En los **19 lenguajes soportados** (ver [Requisitos](/get-started/requisitos)) esto suele significar que tienes árbol incluso cuando Outline aparece vacío. En lenguajes fuera de esa lista (workstream de expansión planificado, ver [Disclaimer](/legal/disclaimer)), no hay árbol — GhostMap no inventa estructura. +- **Fallback automático** cuando el language server no responde o no está disponible, usando Tree-sitter y regex. En los **19 lenguajes soportados** (ver [Requisitos](/get-started/requisitos)) esto suele significar que tienes árbol incluso cuando Outline aparece vacío. En lenguajes fuera de esa lista (workstream de expansión planificado, ver [Disclaimer](/legal/disclaimer)), no hay árbol: GhostMap no inventa estructura. - **Anotaciones `@ghost`** integradas al árbol: TODOs nombrados, regiones marcadas, descripciones con status, todo navegable. -- **Snapshot persistente por archivo** entre sesiones: abrir un archivo previamente visto pinta el árbol en < 50 ms, no hay que esperar al LSP. Hoy esa caché es por documento, no un índice de workspace completo — eso es V2 (ver [Roadmap](/roadmap/vision-v2)). +- **Snapshot persistente por archivo** entre sesiones: abrir un archivo previamente visto pinta el árbol en < 50 ms, no hay que esperar al LSP. Hoy esa caché es por documento, no un índice de workspace completo: eso es V2 (ver [Roadmap](/roadmap/vision-v2)). - **Scanner progresivo** para archivos de 60k líneas sin congelar el editor. - **Diagnósticos** sobre tus anchors y quick fixes. @@ -81,14 +81,14 @@ Sí, uno: **Ctrl+Alt+G** (**Cmd+Alt+G** en macOS) ejecuta `GhostMap: Refresh` mi ## ¿Qué licencia tiene GhostMap V1? -GhostMap V1 se publica como **source-available** bajo la **GhostMap Free Non-Commercial License**: el código es legible y se permite el uso personal, educativo y de evaluación/testing sin costo. El uso comercial, empresarial, en producción o que genere ingresos requiere autorización por escrito (o un futuro flujo de licencia comercial) — no está cubierto por esta licencia ni por donaciones. La visión Enterprise queda como roadmap futuro para integraciones de equipo; no es una funcionalidad disponible hoy. Ver los Términos de uso (incluidos en el repositorio como `LICENSE`; consultas a getghostmap@proton.me) y [Roadmap](/roadmap/vision-v2). +GhostMap V1 se publica como **source-available** bajo la **GhostMap Free Non-Commercial License**: el código es legible y se permite el uso personal, educativo y de evaluación/testing sin costo. El uso comercial, empresarial, en producción o que genere ingresos requiere autorización por escrito (o un futuro flujo de licencia comercial): no está cubierto por esta licencia ni por donaciones. La visión Enterprise queda como roadmap futuro para integraciones de equipo; no es una funcionalidad disponible hoy. Ver los Términos de uso (incluidos en el repositorio como `LICENSE`; consultas a getghostmap@proton.me) y [Roadmap](/roadmap/vision-v2). ## ¿Por qué no aparece GhostMap en VS Code Marketplace u Open VSX todavía? Hoy GhostMap se instala por **VSIX local** construido desde el repo con `npx @vscode/vsce package`. GitHub Releases queda como canal planificado post-tag; todavía no hay release público. -- **VS Code Marketplace — pendiente.** El paquete todavía no tiene `publisher` configurado en `package.json`; falta dar de alta el publisher en Marketplace y completar el primer `vsce publish`. Mientras tanto, instalar por VSIX es funcionalmente equivalente al Marketplace, solo que sin actualizaciones automáticas dentro del editor. -- **Open VSX — planificado.** Será el puente para usuarios de **VSCodium, Cursor, Gitpod** y demás editores que consumen Open VSX en vez del Marketplace de Microsoft. Pensado para publicarse antes o en paralelo con la aprobación en Marketplace. El script de publicación (`publish:open-vsx`, que invoca `ovsx publish`) ya está preparado en `package.json` del repo `genesis`; falta registrar el namespace en open-vsx.org, generar el token y ejecutar el primer publish. +- **VS Code Marketplace: pendiente.** El paquete todavía no tiene `publisher` configurado en `package.json`; falta dar de alta el publisher en Marketplace y completar el primer `vsce publish`. Mientras tanto, instalar por VSIX es funcionalmente equivalente al Marketplace, solo que sin actualizaciones automáticas dentro del editor. +- **Open VSX: planificado.** Será el puente para usuarios de **VSCodium, Cursor, Gitpod** y demás editores que consumen Open VSX en vez del Marketplace de Microsoft. Pensado para publicarse antes o en paralelo con la aprobación en Marketplace. El script de publicación (`publish:open-vsx`, que invoca `ovsx publish`) ya está preparado en `package.json` del repo `genesis`; falta registrar el namespace en open-vsx.org, generar el token y ejecutar el primer publish. Mientras esos canales sean ⏳ pendientes / 🧭 planificados, la ruta oficial es la documentada en **[Instalación](/get-started/instalacion)** y **[Instalar desde VSIX](/vsix-install)**. diff --git a/docs/get-started/instalacion.md b/docs/get-started/instalacion.md index bddc3c5..8b6580a 100644 --- a/docs/get-started/instalacion.md +++ b/docs/get-started/instalacion.md @@ -8,9 +8,8 @@ sidebar_label: Instalación GhostMap es una extensión de Visual Studio Code. No necesitas configurar nada externo: ni servidores, ni cuentas, ni archivos de configuración antes de empezar. -:::note -¿Tienes dudas sobre si GhostMap funcionará en tu máquina o con archivos muy grandes? Consulta [Requisitos mínimos](/get-started/requisitos) antes de instalar. -::: +> **Nota:** +> ¿Tienes dudas sobre si GhostMap funcionará en tu máquina o con archivos muy grandes? Consulta [Requisitos mínimos](/get-started/requisitos) antes de instalar. ## Estado de distribución @@ -26,12 +25,12 @@ Hasta que Marketplace y Open VSX estén publicados, el camino oficial es el VSIX ## Editor -- Visual Studio Code (versión reciente, 1.85 o superior — ver [Requisitos](/get-started/requisitos)). +- Visual Studio Code (versión reciente, 1.85 o superior: ver [Requisitos](/get-started/requisitos)). - Un proyecto en alguno de los 19 lenguajes soportados: JavaScript, TypeScript, JSX, TSX, Python, PHP, Java, C#, Go, Rust, C, C++, Ruby, Dart, Elixir, Groovy, Julia, Objective-C, Scala o Solidity. Si tu lenguaje no tiene un *language server* activo, GhostMap usa automáticamente el mejor respaldo local disponible. En lenguajes Tier 1 suele conservar buen detalle; en Tier 2 o Tier 3 puede producir un árbol más parcial. Consulta [Requisitos mínimos](/get-started/requisitos#matriz-de-calidad-por-lenguaje) antes de tratar el resultado como fuente única de verdad. -## Pasos (camino actual — VSIX por contacto directo) +## Pasos (camino actual: VSIX por contacto directo) 1. Escribí a [getghostmap@proton.me](mailto:getghostmap@proton.me) pidiendo el VSIX. Te respondemos con el archivo `ghostmap-0.5.0.vsix`. Más detalle en **[Instalar desde un archivo VSIX](/vsix-install)**. 2. Abre VS Code. @@ -39,9 +38,8 @@ Si tu lenguaje no tiene un *language server* activo, GhostMap usa automáticamen 4. Menú **"..."** arriba a la derecha → **Install from VSIX...** → selecciona el `.vsix` recibido. 5. Recarga VS Code cuando te lo pida. -:::note -El repositorio `genesis` (código fuente) es privado. Clonarlo y empaquetar localmente solo es posible si te otorgaron acceso explícito; no es un camino de auto-servicio. -::: +> **Nota:** +> El repositorio `genesis` (código fuente) es privado. Clonarlo y empaquetar localmente solo es posible si te otorgaron acceso explícito; no es un camino de auto-servicio. Alternativa por línea de comandos: @@ -58,7 +56,7 @@ Estos pasos quedan documentados para usarse cuando los canales correspondientes ## Verifica que quedó instalada -Abre cualquier archivo de código en un lenguaje soportado. En la barra lateral de VS Code debería aparecer un nuevo panel llamado **GhostMap** (icono de fantasma). Si el archivo todavía no tiene anotaciones `@ghost`, el panel se mostrará vacío — es el comportamiento esperado. +Abre cualquier archivo de código en un lenguaje soportado. En la barra lateral de VS Code debería aparecer un nuevo panel llamado **GhostMap** (icono de fantasma). Si el archivo todavía no tiene anotaciones `@ghost`, el panel se mostrará vacío: es el comportamiento esperado. ## Siguiente paso diff --git a/docs/get-started/primeros-5-minutos.md b/docs/get-started/primeros-5-minutos.md index 651ba4e..ffcac3e 100644 --- a/docs/get-started/primeros-5-minutos.md +++ b/docs/get-started/primeros-5-minutos.md @@ -8,11 +8,11 @@ sidebar_label: Primeros 5 minutos Esta guía te lleva de cero a tu primer Ghost Tree funcionando, sin teoría previa. Si después quieres entender el *por qué* de cada pieza, la sección [Guía / Conceptos](/guide/philosophy) lo cubre en detalle. -## Paso 1 — Abre cualquier archivo de tu proyecto +## Paso 1: Abre cualquier archivo de tu proyecto El panel **GhostMap** aparece en la barra lateral. Si el archivo no tiene anotaciones todavía, el panel se ve vacío. -## Paso 2 — Escribe `gh` y presiona Tab encima de una función o clase +## Paso 2: Escribe `gh` y presiona Tab encima de una función o clase ```ts class PaymentService { @@ -36,23 +36,23 @@ class PaymentService { } ``` -## Paso 3 — Completa la descripción y guarda +## Paso 3: Completa la descripción y guarda ```ts // @ghost charge description: falta validar montos negativos | status: todo charge(amount: number) { ``` -## Paso 4 — Mira el panel GhostMap +## Paso 4: Mira el panel GhostMap ```text PaymentService -└── charge (todo) — falta validar montos negativos +└── charge (todo): falta validar montos negativos ``` -## Paso 5 — Crea tu primer Anchor con nombre propio +## Paso 5: Crea tu primer Anchor con nombre propio -Un Anchor con `#nombre` no necesita estar atado a ninguna función — es ideal para notas generales del archivo o del módulo: +Un Anchor con `#nombre` no necesita estar atado a ninguna función: es ideal para notas generales del archivo o del módulo: ```ts // @ghost #pendientes-pagos description: revisar integración con Stripe v2 | status: review @@ -60,11 +60,11 @@ Un Anchor con `#nombre` no necesita estar atado a ninguna función — es ideal ```text PaymentService -└── charge (todo) — falta validar montos negativos -pendientes-pagos (review) — revisar integración con Stripe v2 +└── charge (todo): falta validar montos negativos +pendientes-pagos (review): revisar integración con Stripe v2 ``` -## Paso 6 — Filtra +## Paso 6: Filtra Haz clic en el ícono de filtro del panel → elige `todo` → solo verás los Ghosts pendientes en todo el proyecto. diff --git a/docs/get-started/requisitos.md b/docs/get-started/requisitos.md index c97426f..b7d31ad 100644 --- a/docs/get-started/requisitos.md +++ b/docs/get-started/requisitos.md @@ -17,9 +17,8 @@ GhostMap es una extensión de VS Code. No requiere configuración de servidor, c GhostMap está pensado para **VS Code Desktop**. VS Code Web (`vscode.dev` / `github.dev`) y entornos remotos pueden restringir el filesystem, el Extension Host o las extensiones instaladas; en V1 no se documentan como superficie verificada. Si usas Remote SSH, Dev Containers, WSL o Codespaces, valida el comportamiento en tu entorno antes de depender de GhostMap para trabajo crítico. -:::note -GhostMap fue desarrollado y probado principalmente en Windows. Las rutas de archivos usan `path.sep` para compatibilidad cross-platform, pero macOS y Linux no han sido verificados de forma exhaustiva en V1. Si encuentras un problema específico de plataforma, escríbenos a [getghostmap@proton.me](mailto:getghostmap@proton.me). -::: +> **Nota:** +> GhostMap fue desarrollado y probado principalmente en Windows. Las rutas de archivos usan `path.sep` para compatibilidad cross-platform, pero macOS y Linux no han sido verificados de forma exhaustiva en V1. Si encuentras un problema específico de plataforma, escríbenos a [getghostmap@proton.me](mailto:getghostmap@proton.me). ## Lenguaje del proyecto @@ -34,22 +33,21 @@ La única dependencia opcional que mejora la calidad del árbol es tener activo | Tier | Qué puedes esperar | Lenguajes | |---|---|---| -| **Tier 1 — first-class** | Extracción de símbolos y nesting completo en los fixtures actuales. Es el nivel recomendado para evaluar GhostMap. | TypeScript, TSX, JavaScript, JSX, Python, Rust, C#, Java, C++, C, PHP, Ruby, Dart | -| **Tier 2 — best-effort** | Símbolos principales disponibles; el nesting o algunos constructos pueden ser parciales según el archivo. | Go, Groovy, Objective-C | -| **Tier 3 — top-level only** | Índice grueso útil para orientación básica; el nesting profundo no debe asumirse como confiable. | Scala, Solidity, Julia, Elixir | +| **Tier 1: first-class** | Extracción de símbolos y nesting completo en los fixtures actuales. Es el nivel recomendado para evaluar GhostMap. | TypeScript, TSX, JavaScript, JSX, Python, Rust, C#, Java, C++, C, PHP, Ruby, Dart | +| **Tier 2: best-effort** | Símbolos principales disponibles; el nesting o algunos constructos pueden ser parciales según el archivo. | Go, Groovy, Objective-C | +| **Tier 3: top-level only** | Índice grueso útil para orientación básica; el nesting profundo no debe asumirse como confiable. | Scala, Solidity, Julia, Elixir | Si tu lenguaje cae en Tier 2 o Tier 3, el fallback sigue intentando darte un árbol útil, pero la precisión esperada es menor que en Tier 1. Para flujos críticos, verifica el resultado contra el archivo antes de usarlo como fuente única de verdad. -:::note Expansión de lenguajes — workstream separado -Hay aproximadamente 20 lenguajes adicionales planificados (Kotlin, Swift, Haskell, OCaml, Lua, R, Bash, familia SQL, …). Son un workstream aparte, bloqueado por: - -- empaquetado de las gramáticas Tree-sitter y procedencia reproducible de los WASM, -- validez de los queries que escribimos o forkeamos contra la versión exacta de la gramática, -- cobertura de fixtures por lenguaje en `test/matrix/`, -- y, en algunos casos, PRs upstream a las propias gramáticas. - -Esos lenguajes **no** se anuncian como soportados hasta cumplir ese gate. Si el ítem que abres está en uno de ellos, GhostMap se comportará igual que en un lenguaje desconocido (no aparecerá árbol de símbolos). Ver [Disclaimer](/legal/disclaimer). -::: +> **Expansión de lenguajes: workstream separado:** +> Hay aproximadamente 20 lenguajes adicionales planificados (Kotlin, Swift, Haskell, OCaml, Lua, R, Bash, familia SQL, …). Son un workstream aparte, bloqueado por: +> +> - empaquetado de las gramáticas Tree-sitter y procedencia reproducible de los WASM, +> - validez de los queries que escribimos o forkeamos contra la versión exacta de la gramática, +> - cobertura de fixtures por lenguaje en `test/matrix/`, +> - y, en algunos casos, PRs upstream a las propias gramáticas. +> +> Esos lenguajes **no** se anuncian como soportados hasta cumplir ese gate. Si el ítem que abres está en uno de ellos, GhostMap se comportará igual que en un lenguaje desconocido (no aparecerá árbol de símbolos). Ver [Disclaimer](/legal/disclaimer). ## RAM y CPU diff --git a/docs/guide/contextual-anchor.md b/docs/guide/contextual-anchor.md index 1e7d8a8..5ff3507 100644 --- a/docs/guide/contextual-anchor.md +++ b/docs/guide/contextual-anchor.md @@ -18,7 +18,7 @@ function processPayment() {} ``` ```text -processPayment (review) — revisar manejo de errores +processPayment (review): revisar manejo de errores ``` ## Cuándo usarlo diff --git a/docs/guide/ghost-description.md b/docs/guide/ghost-description.md index 8d4d351..7fb349e 100644 --- a/docs/guide/ghost-description.md +++ b/docs/guide/ghost-description.md @@ -20,7 +20,7 @@ function login() {} Resultado en el árbol: ```text -login (todo) — este método no maneja refresh tokens todavía +login (todo): este método no maneja refresh tokens todavía ``` No hay límite de formato sobre el texto: puede ser una frase corta, una referencia a un ticket, o una nota arquitectónica más larga. diff --git a/docs/guide/ghost-metadata.md b/docs/guide/ghost-metadata.md index 69452a2..04517d6 100644 --- a/docs/guide/ghost-metadata.md +++ b/docs/guide/ghost-metadata.md @@ -24,7 +24,7 @@ function login() {} Resultado en el árbol: ```text -login (todo) — validar tokens JWT +login (todo): validar tokens JWT ``` **No** se genera un nodo independiente llamado `login` más un nodo Ghost separado. La metadata vive *dentro* del nodo `login`. diff --git a/docs/guide/ownership-radius.md b/docs/guide/ownership-radius.md index d95f774..b138e0e 100644 --- a/docs/guide/ownership-radius.md +++ b/docs/guide/ownership-radius.md @@ -12,9 +12,9 @@ Cuando un [Contextual Anchor](/guide/contextual-anchor) no tiene un símbolo en ## Posibles resultados (Ownership Resolution) -- **Resolved** — existe un único símbolo cercano → la metadata se adjunta. -- **Detached** — no existe ningún símbolo válido cerca → diagnóstico informativo. -- **Ambiguous** — existen múltiples candidatos igual de cercanos → diagnóstico informativo listando los candidatos. +- **Resolved**: existe un único símbolo cercano → la metadata se adjunta. +- **Detached**: no existe ningún símbolo válido cerca → diagnóstico informativo. +- **Ambiguous**: existen múltiples candidatos igual de cercanos → diagnóstico informativo listando los candidatos. ## Ejemplo @@ -25,7 +25,7 @@ function login() {} ``` ```text -login (todo) — mejorar validación +login (todo): mejorar validación ``` A pesar de la línea en blanco entre el comentario y la función, GhostMap resuelve la metadata al símbolo `login` porque está dentro del radio configurado. diff --git a/docs/guide/philosophy.md b/docs/guide/philosophy.md index 13c3daa..18e0a4f 100644 --- a/docs/guide/philosophy.md +++ b/docs/guide/philosophy.md @@ -8,7 +8,7 @@ sidebar_label: Filosofía ## Code-first -La planificación vive junto al código, no en una herramienta externa. Un Ghost no es un ticket que vive en otro lado y que hay que sincronizar manualmente — es una anotación que está físicamente en el archivo que describe. +La planificación vive junto al código, no en una herramienta externa. Un Ghost no es un ticket que vive en otro lado y que hay que sincronizar manualmente: es una anotación que está físicamente en el archivo que describe. ## Una gramática mínima y agnóstica de lenguaje @@ -28,18 +28,18 @@ Metadata Ghost (description, status) Árbol (Ghost Tree) ``` -Primero existe un mapa de **símbolos** del proyecto —extraído del código real, con o sin anotaciones—. Después, la metadata Ghost se adjunta a esos símbolos. Esto es lo que permite que GhostMap entienda la estructura de tu proyecto incluso antes de que empieces a anotar nada. +Primero existe un mapa de **símbolos** del proyecto (extraído del código real, con o sin anotaciones). Después, la metadata Ghost se adjunta a esos símbolos. Esto es lo que permite que GhostMap entienda la estructura de tu proyecto incluso antes de que empieces a anotar nada. ## Principios de diseño -1. **Code first** — el código es la fuente de verdad. -2. **Minimal syntax** — una gramática simple, sin ceremonia. -3. **Language agnostic** — funciona igual en más de 15 lenguajes. -4. **Fast navigation** — un clic te lleva exactamente al lugar correcto. -5. **Structural understanding** — el árbol refleja la jerarquía real del código. -6. **AI-ready architecture** — la gramática está pensada para ser leída por modelos de IA tan fácilmente como por humanos. -7. **Workspace awareness** — GhostMap entiende el proyecto, no solo el archivo abierto. -8. **Incremental scalability** — funciona igual de bien en un archivo de 50 líneas que en uno de 50,000 (ver [Loading Policy](/architecture/loading-policy)). +1. **Code first**: el código es la fuente de verdad. +2. **Minimal syntax**: una gramática simple, sin ceremonia. +3. **Language agnostic**: funciona igual en más de 15 lenguajes. +4. **Fast navigation**: un clic te lleva exactamente al lugar correcto. +5. **Structural understanding**: el árbol refleja la jerarquía real del código. +6. **AI-ready architecture**: la gramática está pensada para ser leída por modelos de IA tan fácilmente como por humanos. +7. **Workspace awareness**: GhostMap entiende el proyecto, no solo el archivo abierto. +8. **Incremental scalability**: funciona igual de bien en un archivo de 50 líneas que en uno de 50,000 (ver [Loading Policy](/architecture/loading-policy)). ## Siguiente paso diff --git a/docs/guide/range-anchor.md b/docs/guide/range-anchor.md index 23889c3..69e080b 100644 --- a/docs/guide/range-anchor.md +++ b/docs/guide/range-anchor.md @@ -23,7 +23,7 @@ class PaymentService { ``` ```text -refactor-pagos (todo) — dividir este servicio en 3 +refactor-pagos (todo): dividir este servicio en 3 └── PaymentService ├── charge ├── refund @@ -33,7 +33,7 @@ refactor-pagos (todo) — dividir este servicio en 3 ## Reglas de jerarquía (containment) - Un símbolo que **empieza** dentro del rango de un Range Anchor pertenece a ese anchor, incluso si su cuerpo se extiende más allá de la línea `@ghost end`. -- La jerarquía se construye por **contención de rangos**, no por nombres compuestos: nunca verás algo como `AuthService.login()` como identificador — la relación padre-hijo se expresa directamente en el árbol. +- La jerarquía se construye por **contención de rangos**, no por nombres compuestos: nunca verás algo como `AuthService.login()` como identificador: la relación padre-hijo se expresa directamente en el árbol. ## Importante: el nombre es obligatorio para que se vea @@ -49,7 +49,7 @@ Un `@ghost ... start` **sin** `#nombre` es válido sintácticamente, pero al no ## Ejemplo antes / después -**Antes** — un archivo grande, sin estructura, donde un dev nuevo no sabe por dónde empezar ni qué partes están "en obras": +**Antes**: un archivo grande, sin estructura, donde un dev nuevo no sabe por dónde empezar ni qué partes están "en obras": ```ts class PaymentService { @@ -68,7 +68,7 @@ PaymentService └── generateInvoice ``` -**Después** — con un Range Anchor agrupando el trabajo en curso: +**Después**: con un Range Anchor agrupando el trabajo en curso: ```ts // @ghost #refactor-pagos start description: dividir este servicio en 3 microservicios | status: in-progress @@ -87,11 +87,11 @@ class PaymentService { ``` ```text -refactor-pagos (in-progress) — dividir este servicio en 3 microservicios +refactor-pagos (in-progress): dividir este servicio en 3 microservicios └── PaymentService ├── charge ├── refund - ├── reconcile (todo) — pendiente mover a billing-service + ├── reconcile (todo): pendiente mover a billing-service └── generateInvoice ``` diff --git a/docs/guide/semantic-anchor.md b/docs/guide/semantic-anchor.md index f63254d..7240fa8 100644 --- a/docs/guide/semantic-anchor.md +++ b/docs/guide/semantic-anchor.md @@ -15,7 +15,7 @@ Un **Semantic Anchor** es un Anchor con nombre explícito (`#nombre`). - Tiene nombre propio (`#auth`, `#refactor-pagos`, etc.). - Aparece en el árbol como nodo propio. - Puede contener otros elementos (si se usa como [Range Anchor](/guide/range-anchor)). -- Puede existir de forma totalmente independiente, sin estar pegado a ningún símbolo de código — por ejemplo, para una nota arquitectónica general. +- Puede existir de forma totalmente independiente, sin estar pegado a ningún símbolo de código: por ejemplo, para una nota arquitectónica general. ## Ejemplo @@ -24,7 +24,7 @@ Un **Semantic Anchor** es un Anchor con nombre explícito (`#nombre`). ``` ```text -auth (todo) — validar JWT +auth (todo): validar JWT ``` ## Siguiente paso diff --git a/docs/guide/symbol-validity-gate.md b/docs/guide/symbol-validity-gate.md index 246710a..b1b4eea 100644 --- a/docs/guide/symbol-validity-gate.md +++ b/docs/guide/symbol-validity-gate.md @@ -15,7 +15,7 @@ El **Symbol Validity Gate** es un filtro centralizado que decide si un nombre ex - Tiene menos de 2 caracteres, o es `` / empieza con `<`. - Es un identificador de 1–2 letras en minúscula (`e`, `cb`, `fn`...). - Está en la lista de "nombres ruido" (`NOISE_NAMES`): `callback`, `cb`, `fn`, `func`, `handler`, `resolve`, `reject`, `next`, `done`, `err`, `error`, `e`, `evt`, `event`, `res`, `req`, `ctx`, `data`, `item`, `then`, `catch`, `finally`, `body`, `args`, `kwargs`, `params`, `opts`, `options`. -- Es una palabra reservada del lenguaje (lista cross-language: `if`, `class`, `function`, `return`, `async`, `self`, `this`, etc. — más de 100 palabras cubriendo JS/TS, Python, Rust, Go, Java, C#, C/C++, Ruby, SQL, entre otros). +- Es una palabra reservada del lenguaje (lista cross-language: `if`, `class`, `function`, `return`, `async`, `self`, `this`, etc.: más de 100 palabras cubriendo JS/TS, Python, Rust, Go, Java, C#, C/C++, Ruby, SQL, entre otros). ## Por qué importa @@ -44,9 +44,8 @@ class Foo { function calculateMonthlyInterest(principal: number) {} ``` -:::tip -Si una función o variable que esperabas ver no aparece en el árbol, probablemente cae en uno de estos casos — no es un error de GhostMap. -::: +> **Nota:** +> Si una función o variable que esperabas ver no aparece en el árbol, probablemente cae en uno de estos casos: no es un error de GhostMap. ## Siguiente paso diff --git a/docs/guide/symbol.md b/docs/guide/symbol.md index 5f2db54..755527c 100644 --- a/docs/guide/symbol.md +++ b/docs/guide/symbol.md @@ -16,17 +16,17 @@ GhostMap reconoce: **Class, Function, Method, Interface, Struct, Enum**. Internamente se agrupan en dos categorías: -- `'function'` — incluye Function, Method y Constructor. -- `'class'` — incluye Class, Interface, Struct y Enum. +- `'function'`: incluye Function, Method y Constructor. +- `'class'`: incluye Class, Interface, Struct y Enum. ## Cómo se extraen GhostMap intenta, en este orden: -1. **LSP** (`vscode.executeDocumentSymbolProvider`) — si el lenguaje tiene un *language server* activo, es la fuente preferida. -2. **Tree-sitter** — gramáticas WASM por lenguaje. -3. **Regex fallback** — patrones por lenguaje cuando no hay LSP ni grammar de tree-sitter disponible (o falla el parseo). -4. **PHP/Blade** — tiene su propio parser regex dedicado. +1. **LSP** (`vscode.executeDocumentSymbolProvider`): si el lenguaje tiene un *language server* activo, es la fuente preferida. +2. **Tree-sitter**: gramáticas WASM por lenguaje. +3. **Regex fallback**: patrones por lenguaje cuando no hay LSP ni grammar de tree-sitter disponible (o falla el parseo). +4. **PHP/Blade**: tiene su propio parser regex dedicado. ## Lenguajes soportados @@ -50,7 +50,7 @@ AuthService (class) └── logout (function) ``` -Nota que este árbol existe **sin ninguna anotación `@ghost`** — es el mapa de símbolos puro. La metadata Ghost se le adjunta encima (ver [Ghost Metadata](/guide/ghost-metadata)). +Nota que este árbol existe **sin ninguna anotación `@ghost`**: es el mapa de símbolos puro. La metadata Ghost se le adjunta encima (ver [Ghost Metadata](/guide/ghost-metadata)). ## Siguiente paso diff --git a/docs/intro.md b/docs/intro.md index d0f3d64..c4f8739 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -2,55 +2,63 @@ id: intro title: GhostMap slug: / -sidebar_label: Introducción +sidebar_label: Start --- -# Estructura de proyecto, dentro de tu código +# Project structure, inside your code -GhostMap es una extensión de VS Code que convierte comentarios estructurados (`@ghost`) en un mapa navegable de tu proyecto: un árbol semántico que vive junto al código, no en una herramienta externa. +GhostMap is a VS Code extension that turns structured `@ghost` comments into a +navigable map of your code. -## El problema +This site starts in English. The detailed reference is still in Spanish. -Los `TODO`, `FIXME` y `HACK` que ya usas no tienen estructura. No se pueden filtrar, no tienen un estado claro y, con el tiempo, se pierden entre miles de líneas. GhostMap les da una gramática mínima y los conecta directamente con los símbolos reales del código: clases, funciones, métodos, interfaces. +## The idea -> *"El código es la fuente principal de verdad. Las tareas, refactorizaciones, documentación pendiente y observaciones arquitectónicas deben existir cerca de la implementación que describen."* +`TODO`, `FIXME`, and `HACK` comments are useful, but they have no structure. +GhostMap gives them a small grammar and connects them to real symbols: classes, +functions, methods, interfaces, and anchors. -## Cómo se ve en la práctica +> The code stays the source of truth. Notes about the code live next to the code. -Este comentario: +## How it looks + +Write this: ```ts class AuthService { - - // @ghost description: revisar seguridad | status: todo + // @ghost description: review security | status: todo login() { // ... } } ``` -se convierte automáticamente en esto, en el panel lateral de GhostMap: +GhostMap shows this in the side panel: ```text AuthService -└── login (todo) — revisar seguridad +└── login (todo): review security ``` -Sin configuración adicional, sin archivos externos. El árbol se reconstruye solo cada vez que editas. +No extra files. No external tracker. The tree rebuilds as you edit. -## Por dónde empezar +## Start here -- **[Instalación](/get-started/instalacion)** — genera un VSIX local e instálalo en VS Code Desktop. -- **[Primeros 5 minutos](/get-started/primeros-5-minutos)** — escribe tu primer `@ghost` y mira aparecer el árbol. -- **[Guía / Conceptos](/guide/philosophy)** — entiende los fundamentos: símbolos, anchors, ownership. -- **[Referencia](/reference/sintaxis)** — sintaxis completa de `@ghost`, comandos y settings. +- **[Install / Access](/en/install)**: current install path and planned channels. +- **[Legal & Support](/en/legal-support)**: license summary and contact. +- **[Spanish install guide](/get-started/instalacion)**: detailed VSIX steps. +- **[Spanish first 5 minutes](/get-started/primeros-5-minutos)**: write your first `@ghost`. +- **[Spanish syntax reference](/reference/sintaxis)**: full `@ghost` syntax, commands, and settings. -## Tres tipos de Ghost +## Three Ghost types -| Tipo | Ejemplo | Qué hace | +| Type | Example | What it does | |---|---|---| -| **Contextual** | `// @ghost description: ... \| status: ...` | Se adjunta automáticamente al símbolo más cercano. | -| **Named (Semantic Anchor)** | `// @ghost #nombre description: ...` | Crea un nodo propio en el árbol, con identidad propia. | -| **Range** | `// @ghost #nombre start ... // @ghost end` | Agrupa una sección completa de código bajo un mismo nodo. | - -GhostMap Core —todo lo cubierto en esta documentación— es el alcance documentado para V1. GhostMap es un producto propiedad del *GhostMap project owner* (MarxWellB), distribuido bajo la **GhostMap Free Non-Commercial License**: uso personal, educativo y de evaluación sin costo; cualquier uso comercial, de empresa, en producción o que genere ingresos requiere autorización escrita. Las consultas de licenciamiento comercial van a [getghostmap@proton.me](mailto:getghostmap@proton.me). +| **Contextual** | `// @ghost description: ... \| status: ...` | Attaches to the nearest symbol. | +| **Named (Semantic Anchor)** | `// @ghost #name description: ...` | Creates its own node in the tree. | +| **Range** | `// @ghost #name start ... // @ghost end` | Groups a whole code section under one node. | + +GhostMap is source-available under the **GhostMap Free Non-Commercial License**. +Personal, educational, and evaluation use is free. Commercial use needs written +authorization. For licensing questions, write to +[getghostmap@proton.me](mailto:getghostmap@proton.me). diff --git a/docs/legal/disclaimer.md b/docs/legal/disclaimer.md index 0e4142a..71fa2a6 100644 --- a/docs/legal/disclaimer.md +++ b/docs/legal/disclaimer.md @@ -10,9 +10,8 @@ sidebar_label: Disclaimer **Effective date:** June 18, 2026 · **Version:** 1.0 -:::caution -GhostMap is currently in pre-release. Some features described in this documentation are best-effort. Read this page before relying on GhostMap output for critical work. -::: +> **Important:** +> GhostMap is currently in pre-release. Some features described in this documentation are best-effort. Read this page before relying on GhostMap output for critical work. ## Pre-release software @@ -46,12 +45,12 @@ These are tracked for resolution in upcoming rounds. Roughly 20 additional languages (Kotlin, Swift, Haskell, OCaml, Clojure, Lua, R, Bash, the SQL family, …) are on the roadmap but **not supported today**. The expansion is gated on a set of validation and packaging risks surfaced by prior audits of the existing 19-grammar bundle: -- **Dart WASM load failure risk** — the Dart grammar has been observed to fail to load on some Electron/Node combinations and silently fall back to regex. -- **Invalid Elixir / Objective-C queries** — existing query files reference nodes the upstream grammars do not always expose; new queries we ship must be validated against the grammar version we bundle. -- **Weak Julia coverage** — many definition shapes (macros, `@inline`-emitted defs) are not extracted; new similar-shape languages need a fixture set proving the shapes we claim to cover. -- **Duplicate symbol issues** — some grammar packs expose colliding WASM symbol names that mis-load at runtime without a duplicate-symbol guard. -- **Non-reproducible WASM provenance** — today's WASMs are checked-in artifacts; the expansion needs a reproducible build job before adding more. -- **Fallback masking broken grammars** — the LSP → Tree-sitter → regex chain hides grammar regressions; the expansion needs a per-grammar load + sample-query smoke that fails loudly. +- **Dart WASM load failure risk**: the Dart grammar has been observed to fail to load on some Electron/Node combinations and silently fall back to regex. +- **Invalid Elixir / Objective-C queries**: existing query files reference nodes the upstream grammars do not always expose; new queries we ship must be validated against the grammar version we bundle. +- **Weak Julia coverage**: many definition shapes (macros, `@inline`-emitted defs) are not extracted; new similar-shape languages need a fixture set proving the shapes we claim to cover. +- **Duplicate symbol issues**: some grammar packs expose colliding WASM symbol names that mis-load at runtime without a duplicate-symbol guard. +- **Non-reproducible WASM provenance**: today's WASMs are checked-in artifacts; the expansion needs a reproducible build job before adding more. +- **Fallback masking broken grammars**: the LSP → Tree-sitter → regex chain hides grammar regressions; the expansion needs a per-grammar load + sample-query smoke that fails loudly. Until a candidate language passes all of those gates (and gets a fixture row in the matrix tests), it does not appear in [Requisitos](/get-started/requisitos) or the language sections of the marketing site. diff --git a/docs/legal/notices.md b/docs/legal/notices.md index 1f0a111..280e2b6 100644 --- a/docs/legal/notices.md +++ b/docs/legal/notices.md @@ -44,7 +44,7 @@ The following 19 grammars ship as precompiled WebAssembly files inside the exten ### Provenance note -The exact git commit/tag used to compile each shipped WASM artifact is not recorded in this repository — the WASMs are checked-in artifacts rather than reproducibly built. Each per-component `SOURCE.txt` records the upstream default-branch HEAD commit at the time the LICENSE text was fetched. The shipped LICENSE files are the best available license notices for the bundled artifacts under that provenance disclosure; if the upstream license for a grammar later changes, the notice that shipped with a given release continues to govern that release. This provenance gap is acknowledged here, not hidden, and will be closed when the WASM build job becomes reproducible (see the language-pack expansion gate in [Disclaimer](/legal/disclaimer)). +The exact git commit/tag used to compile each shipped WASM artifact is not recorded in this repository: the WASMs are checked-in artifacts rather than reproducibly built. Each per-component `SOURCE.txt` records the upstream default-branch HEAD commit at the time the LICENSE text was fetched. The shipped LICENSE files are the best available license notices for the bundled artifacts under that provenance disclosure; if the upstream license for a grammar later changes, the notice that shipped with a given release continues to govern that release. This provenance gap is acknowledged here, not hidden, and will be closed when the WASM build job becomes reproducible (see the language-pack expansion gate in [Disclaimer](/legal/disclaimer)). ## VS Code Extension API diff --git a/docs/legal/privacy.md b/docs/legal/privacy.md index 35d6c74..37a26fc 100644 --- a/docs/legal/privacy.md +++ b/docs/legal/privacy.md @@ -10,9 +10,8 @@ sidebar_label: Privacy Policy **Effective date:** June 20, 2026 · **Version:** 1.1 -:::tip The whole policy in one line -The GhostMap extension runs on your machine, makes no network calls of its own, transmits no source code or metadata off your machine, ships no telemetry or analytics, and does not communicate with the maintainers. Site and support-platform caveats are covered below. -::: +> **The whole policy in one line:** +> The GhostMap extension runs on your machine, makes no network calls of its own, transmits no source code or metadata off your machine, ships no telemetry or analytics, and does not communicate with the maintainers. Site and support-platform caveats are covered below. ## 1. What data we collect @@ -63,7 +62,7 @@ This statement describes the current technical design and maintainer data postur ## 9. Future enterprise-oriented roadmap and server services -The enterprise-oriented integrations described in [Roadmap — Visión v2](/roadmap/vision-v2) (Jira / Slack flow, Ghost Threads, Ghost Graph, dashboards, AI explanations, permissions and audit log) are **not implemented today** and no part of GhostMap currently communicates with any of those services. Nothing in this policy should be read as a commitment that those integrations will exist, or that they will preserve the current local-only posture. +The enterprise-oriented integrations described in [Roadmap: Visión v2](/roadmap/vision-v2) (Jira / Slack flow, Ghost Threads, Ghost Graph, dashboards, AI explanations, permissions and audit log) are **not implemented today** and no part of GhostMap currently communicates with any of those services. Nothing in this policy should be read as a commitment that those integrations will exist, or that they will preserve the current local-only posture. If a future version of GhostMap ever introduces an optional feature that involves data collection or transmission (for example, an optional opt-in telemetry signal, or an Enterprise capability with server services), that feature will be: diff --git a/docs/legal/terms.md b/docs/legal/terms.md index e01f1fc..846ca3b 100644 --- a/docs/legal/terms.md +++ b/docs/legal/terms.md @@ -10,9 +10,8 @@ sidebar_label: Terms of Use **Effective date:** June 20, 2026 · **Version:** 1.2 -:::caution Short version -Personal, educational, evaluation/testing, and other non-commercial use are allowed. Company, production, revenue-generating, resale, white-label, marketplace, and competing commercial-product use require written authorization. -::: +> **Short version:** +> Personal, educational, evaluation/testing, and other non-commercial use are allowed. Company, production, revenue-generating, resale, white-label, marketplace, and competing commercial-product use require written authorization. ## 1. Product identification & ownership @@ -63,7 +62,7 @@ GhostMap incorporates third-party components, each licensed under its own terms. ## 9. Future roadmap and server services -Future team-oriented capabilities and the integrations described in [Roadmap — Visión v2](/roadmap/vision-v2) (Jira / Slack flow, Ghost Threads, Ghost Graph, dashboards, AI explanations, permissions and audit log) are **not implemented today**. Future commercial or server-service components, if released, will carry their own license terms and privacy notices, and will require an explicit opt-in before any data leaves a user's machine. Nothing in these Terms should be read as a commitment that such components will exist or that they will preserve the local-only posture of V1. +Future team-oriented capabilities and the integrations described in [Roadmap: Visión v2](/roadmap/vision-v2) (Jira / Slack flow, Ghost Threads, Ghost Graph, dashboards, AI explanations, permissions and audit log) are **not implemented today**. Future commercial or server-service components, if released, will carry their own license terms and privacy notices, and will require an explicit opt-in before any data leaves a user's machine. Nothing in these Terms should be read as a commitment that such components will exist or that they will preserve the local-only posture of V1. ## 10. Privacy @@ -85,11 +84,11 @@ These terms are governed by the law of the maintainer's jurisdiction, except whe ## 14. Changes to these terms -These terms, the license model, and supporter-benefit framing may change for future versions of GhostMap. Changes do not retroactively remove personal, educational, evaluation/testing, or other non-commercial permission already granted for versions you obtained under the then-current license. Changes may affect future versions and any future commercial authorization. The product owner reserves the right to revise the license model — including the structure of allowed and prohibited use, the supporter benefits framework, and any future commercial licensing system — for future versions. +These terms, the license model, and supporter-benefit framing may change for future versions of GhostMap. Changes do not retroactively remove personal, educational, evaluation/testing, or other non-commercial permission already granted for versions you obtained under the then-current license. Changes may affect future versions and any future commercial authorization. The product owner reserves the right to revise the license model (including the structure of allowed and prohibited use, the supporter benefits framework, and any future commercial licensing system) for future versions. ## 15. Intellectual property -All intellectual property in GhostMap — the original source code, the Ghost-prefixed vocabulary, the ghost mark, documentation, screenshots, and product copy on this docs site and the marketing site — is owned by the GhostMap project owner. Nothing in these terms transfers ownership of GhostMap intellectual property to any user, supporter, or licensee. Permitted use under section 2 and any commercial license under section 5 grant only the use described in those sections; they do not transfer ownership. +All intellectual property in GhostMap (the original source code, the Ghost-prefixed vocabulary, the ghost mark, documentation, screenshots, and product copy on this docs site and the marketing site) is owned by the GhostMap project owner. Nothing in these terms transfers ownership of GhostMap intellectual property to any user, supporter, or licensee. Permitted use under section 2 and any commercial license under section 5 grant only the use described in those sections; they do not transfer ownership. ## 16. Contact diff --git a/docs/reference/diagnostics.md b/docs/reference/diagnostics.md index 11efa80..698c26a 100644 --- a/docs/reference/diagnostics.md +++ b/docs/reference/diagnostics.md @@ -20,11 +20,11 @@ GhostMap muestra advertencias e información directamente en el editor cuando de ## Code Actions disponibles -- **"Add @ghost annotation"** — sobre una línea `function`/`class` sin anotación previa, inserta una línea `// @ghost description: | status: todo` justo arriba. -- **"Convert to semantic anchor: @ghost #token"** / **"Convert to contextual anchor: @ghost description: …"** — sobre sintaxis híbrida malformada. +- **"Add @ghost annotation"**: sobre una línea `function`/`class` sin anotación previa, inserta una línea `// @ghost description: | status: todo` justo arriba. +- **"Convert to semantic anchor: @ghost #token"** / **"Convert to contextual anchor: @ghost description: …"**: sobre sintaxis híbrida malformada. - **Fix de clave mal escrita** (`statu:` → `status:`) cuando la clave contiene "stat"/"statu" pero no es exactamente `status` o `description`. -- **Fix de valor de status inválido** — sugiere el status soportado más parecido (por prefijo) o `todo`. -- **"Add #anchor name"** — sobre una línea `@ghost` sin `#`, `start` ni `end` que no es el anchor más cercano a ningún símbolo, sugiere agregar `#name`. +- **Fix de valor de status inválido**: sugiere el status soportado más parecido (por prefijo) o `todo`. +- **"Add #anchor name"**: sobre una línea `@ghost` sin `#`, `start` ni `end` que no es el anchor más cercano a ningún símbolo, sugiere agregar `#name`. ## Siguiente paso diff --git a/docs/reference/ghost-tree.md b/docs/reference/ghost-tree.md index 5cf7c8d..973181f 100644 --- a/docs/reference/ghost-tree.md +++ b/docs/reference/ghost-tree.md @@ -10,7 +10,7 @@ sidebar_label: Ghost Tree El árbol se construye por **contención de rangos**, no por nombres compuestos. -**Regla de pertenencia:** el nodo A es padre de B si `A.start <= B.start` y `A.end > B.start` — es decir, B "nace" dentro del rango de A, aunque su cuerpo se extienda más allá. +**Regla de pertenencia:** el nodo A es padre de B si `A.start <= B.start` y `A.end > B.start`: es decir, B "nace" dentro del rango de A, aunque su cuerpo se extienda más allá. ## Ejemplo combinando símbolos y anchors @@ -29,9 +29,9 @@ class PaymentService { ``` ```text -pagos (in-progress) — módulo de pagos v2 +pagos (in-progress): módulo de pagos v2 └── PaymentService - ├── charge (todo) — falta manejar timeouts + ├── charge (todo): falta manejar timeouts └── refund ``` @@ -42,7 +42,7 @@ El panel lateral "GhostMap" muestra el árbol con iconos por tipo de nodo: - 🔵 Function/Method/Constructor → ícono de método (azul). - 🟣 Class/Interface/Struct/Enum → ícono de clase (morado). - 🟢 Anchor → ícono de bookmark (verde). -- ⚪ Nodo "de contexto" — visible solo porque un hijo coincide con un filtro/búsqueda activa → ícono atenuado con la etiqueta `(context)`. +- ⚪ Nodo "de contexto": visible solo porque un hijo coincide con un filtro/búsqueda activa → ícono atenuado con la etiqueta `(context)`. Hacer clic en un nodo navega directamente a la línea correspondiente y resalta brevemente el rango. @@ -62,7 +62,7 @@ Todos los comandos aparecen en la paleta de comandos de VS Code agrupados bajo l - **Filtro por tipo:** `function` / `class` / `anchor` / Todos. - **Filtro por status:** lista dinámica de los estados presentes en el proyecto, con conteo (`todo (5)`, `in-progress (2)`, etc.). El último filtro de status usado se recuerda entre sesiones. - **Búsqueda libre:** filtra por nombre o por contenido de `description` (sin distinguir mayúsculas/minúsculas). -- **Visibilidad por burbuja:** si un hijo cumple el filtro/búsqueda, su(s) padre(s) permanecen visibles —marcados como "contexto"— aunque no cumplan el filtro por sí mismos. Así nunca se pierde la ubicación del resultado dentro del árbol. +- **Visibilidad por burbuja:** si un hijo cumple el filtro/búsqueda, su(s) padre(s) permanecen visibles (marcados como "contexto") aunque no cumplan el filtro por sí mismos. Así nunca se pierde la ubicación del resultado dentro del árbol. ## Siguiente paso diff --git a/docs/reference/rendimiento.md b/docs/reference/rendimiento.md index b8e7435..fbdaadc 100644 --- a/docs/reference/rendimiento.md +++ b/docs/reference/rendimiento.md @@ -28,15 +28,14 @@ Cada capa es más rápida y menos precisa que la anterior. En la mayoría de los | Archivo pequeño (< 500 líneas) con LSP activo | **200 – 600 ms** | | Archivo 60k líneas, scanner progresivo | **~33 ms** de scan puro | | LSP cold start en condiciones normales | **800 ms – 3 s** | -| LSP cold start bajo presión de RAM (80–90%) | **5 – 35 s** (GhostMap no espera — cae al fallback a los 800 ms) | +| LSP cold start bajo presión de RAM (80–90%) | **5 – 35 s** (GhostMap no espera: cae al fallback a los 800 ms) | -:::tip Ghost Index es la clave -El escenario más común después de la primera apertura es siempre el primero: < 50 ms desde snapshot. La primera apertura de un archivo paga el costo de extracción; todas las siguientes no. -::: +> **Ghost Index es la clave:** +> El escenario más común después de la primera apertura es siempre el primero: < 50 ms desde snapshot. La primera apertura de un archivo paga el costo de extracción; todas las siguientes no. ## El scanner progresivo (archivos grandes) -Para archivos de 50,000 líneas o más, GhostMap usa un scanner basado en regex que cede el control al event loop de VS Code entre lotes — el editor no se congela mientras analiza. +Para archivos de 50,000 líneas o más, GhostMap usa un scanner basado en regex que cede el control al event loop de VS Code entre lotes: el editor no se congela mientras analiza. - Tamaño de lote: 4,000 líneas por iteración. - Primeros 50 símbolos se publican en el árbol antes de terminar el análisis completo. El árbol aparece rápido y se va completando. diff --git a/docs/reference/sintaxis.md b/docs/reference/sintaxis.md index eb48268..1667a20 100644 --- a/docs/reference/sintaxis.md +++ b/docs/reference/sintaxis.md @@ -73,9 +73,8 @@ Escribir `gh` seguido de **Tab** directamente sobre una línea vacía activa un - Si no hay símbolo cercano → sugiere `// @ghost #name description: ... | status: todo` (Semantic). - Si hay **varios** candidatos igual de cercanos → sugiere primero el más cercano como contextual, luego ofrece la opción semántica (para evitar ambigüedad) y una opción contextual por cada candidato adicional. -:::note -El autocompletado solo sugiere símbolos definidos **más abajo** en el archivo, dentro del rango de ownership configurado. -::: +> **Nota:** +> El autocompletado solo sugiere símbolos definidos **más abajo** en el archivo, dentro del rango de ownership configurado. ## 4.5 Reglas gramaticales y errores comunes @@ -94,7 +93,7 @@ El autocompletado solo sugiere símbolos definidos **más abajo** en el archivo, En V1, un Anchor solo es válido si está escrito como **comentario de línea**: `// @ghost ...` o `# @ghost ...`. -Comentarios de bloque o JSDoc (`/* @ghost ... */`, `/** @ghost ... */`) **no son evidencia válida de anchor en V1** y son ignorados por el parser. Si un `@ghost` dentro de un bloque `/** ... */` no aparece en el árbol, este es el comportamiento esperado — el soporte para comentarios de bloque podría llegar en una versión futura. +Comentarios de bloque o JSDoc (`/* @ghost ... */`, `/** @ghost ... */`) **no son evidencia válida de anchor en V1** y son ignorados por el parser. Si un `@ghost` dentro de un bloque `/** ... */` no aparece en el árbol, este es el comportamiento esperado: el soporte para comentarios de bloque podría llegar en una versión futura. ## Siguiente paso diff --git a/docs/roadmap/vision-v2.md b/docs/roadmap/vision-v2.md index 49ff53f..aba469a 100644 --- a/docs/roadmap/vision-v2.md +++ b/docs/roadmap/vision-v2.md @@ -1,24 +1,23 @@ --- id: vision-v2 -title: 'Roadmap — Visión v2' +title: 'Roadmap: Visión v2' sidebar_label: Visión v2 --- -# Roadmap — Visión v2 +# Roadmap: Visión v2 -GhostMap Core —todo lo descrito en el resto de esta documentación— es el alcance de V1 bajo la **GhostMap Free Non-Commercial License** (source-available, uso no comercial). Lo que sigue es la visión para futuras capacidades Enterprise, pensadas para equipos donde esta información necesita fluir entre la capa técnica, operativa y directiva; su uso comercial requeriría autorización por escrito o un futuro flujo de licencia. +GhostMap Core (todo lo descrito en el resto de esta documentación) es el alcance de V1 bajo la **GhostMap Free Non-Commercial License** (source-available, uso no comercial). Lo que sigue es la visión para futuras capacidades Enterprise, pensadas para equipos donde esta información necesita fluir entre la capa técnica, operativa y directiva; su uso comercial requeriría autorización por escrito o un futuro flujo de licencia. -:::caution Nada de esta sección está publicado -Todo lo descrito en esta página — Ghost Index v2, Ghost Watcher, Ghost Threads, Ghost Graph, dashboards, explicaciones con IA, integraciones con Jira / Slack, permisos / audit log — es **dirección a futuro**, no funcionalidad disponible en V1 (0.5.x). Lo que ya funciona hoy se describe en el resto de la documentación. +> **Nada de esta sección está publicado:** +> Todo lo descrito en esta página (Ghost Index v2, Ghost Watcher, Ghost Threads, Ghost Graph, dashboards, explicaciones con IA, integraciones con Jira / Slack, permisos / audit log) es **dirección a futuro**, no funcionalidad disponible en V1 (0.5.x). Lo que ya funciona hoy se describe en el resto de la documentación. +> +> Cualquier integración con servicios de servidor que aparezca a futuro requerirá su propia divulgación en la Privacy Policy de GhostMap y un consentimiento explícito antes de enviar datos fuera de tu máquina (para una copia actual, escribir a [getghostmap@proton.me](mailto:getghostmap@proton.me)). Nada en este roadmap es una promesa de fecha ni de alcance final. -Cualquier integración con servicios de servidor que aparezca a futuro requerirá su propia divulgación en la Privacy Policy de GhostMap y un consentimiento explícito antes de enviar datos fuera de tu máquina (para una copia actual, escribir a [getghostmap@proton.me](mailto:getghostmap@proton.me)). Nada en este roadmap es una promesa de fecha ni de alcance final. -::: - -## V2 — motor de indexación workspace-wide (planificado) +## V2: motor de indexación workspace-wide (planificado) **Estado hoy (V1, 0.5.x):** el Ghost Tree se calcula por archivo activo. Cada archivo abierto persiste su snapshot en `.ghostmap/ghostmap.json` (ver [Local State](/architecture/local-state)). Eso es una **caché por documento**, no un índice de workspace. No hay file-system watcher ni validador de fingerprint en background (el intento anterior se quitó por congelar el Extension Host). -**Dirección V2 (no publicada):** un índice persistente a nivel de workspace — el **Ghost Index v2** — construido con shards JSON por carpeta de primer nivel, mantenido actualizado incrementalmente por un **Ghost Watcher** sobre el filesystem y validado fuera de banda por un **Ghost Validator** en un worker thread (mtime prefilter + SHA-256 en stream). El path de refresh del archivo activo (la responsividad V1) se preserva: el motor V2 se *capa* por debajo, no lo reemplaza. +**Dirección V2 (no publicada):** un índice persistente a nivel de workspace (el **Ghost Index v2**) construido con shards JSON por carpeta de primer nivel, mantenido actualizado incrementalmente por un **Ghost Watcher** sobre el filesystem y validado fuera de banda por un **Ghost Validator** en un worker thread (mtime prefilter + SHA-256 en stream). El path de refresh del archivo activo (la responsividad V1) se preserva: el motor V2 se *capa* por debajo, no lo reemplaza. **Beneficio si se publica:** apertura de cualquier archivo del workspace en milisegundos desde el índice, navegación cross-archivo y base para integraciones más ricas. Hasta que se publique, sigue siendo dirección de roadmap. @@ -36,23 +35,22 @@ Independiente del motor V2, hay un workstream para añadir ~20 lenguajes adicion Ver [Disclaimer → Language pack expansion](/legal/disclaimer) y la sección "Expansión de lenguajes" en [Requisitos](/get-started/requisitos). -:::caution Gate antes de integraciones futuras -Antes de publicar cualquier integración con Jira, Slack, IA, dashboards o servicios de servidor, GhostMap necesita cerrar estos puntos como requisitos de producto, no como detalles opcionales: - -- **Permisos y roles:** qué acciones puede iniciar una persona, cuáles puede sugerir un agente, y cuáles requieren aprobación explícita. -- **Modelo de datos:** qué campos se guardan localmente, cuáles viajan a servicios externos, cómo se versionan y cómo se eliminan. -- **Consentimiento y privacidad:** aviso actualizado, consentimiento in-editor antes de transmitir datos, y separación clara entre V1 local-only y futuras capacidades conectadas. -- **Pruebas de recuperación:** escenarios de permisos revocados, tokens expirados, integraciones caídas, conflictos de escritura y rollback seguro si una automatización falla. - -Hasta que esos gates existan y estén verificados, las capacidades conectadas siguen siendo visión, no producto publicado. -::: +> **Gate antes de integraciones futuras:** +> Antes de publicar cualquier integración con Jira, Slack, IA, dashboards o servicios de servidor, GhostMap necesita cerrar estos puntos como requisitos de producto, no como detalles opcionales: +> +> - **Permisos y roles:** qué acciones puede iniciar una persona, cuáles puede sugerir un agente, y cuáles requieren aprobación explícita. +> - **Modelo de datos:** qué campos se guardan localmente, cuáles viajan a servicios externos, cómo se versionan y cómo se eliminan. +> - **Consentimiento y privacidad:** aviso actualizado, consentimiento in-editor antes de transmitir datos, y separación clara entre V1 local-only y futuras capacidades conectadas. +> - **Pruebas de recuperación:** escenarios de permisos revocados, tokens expirados, integraciones caídas, conflictos de escritura y rollback seguro si una automatización falla. +> +> Hasta que esos gates existan y estén verificados, las capacidades conectadas siguen siendo visión, no producto publicado. -## Pilar 1 — Retomar el trabajo sin fricción +## Pilar 1: Retomar el trabajo sin fricción Un dev termina su día. Al siguiente, abre VS Code y GhostMap. - **Dashboard general** que muestra el estado de todos los archivos y los Ghosts marcados como urgentes. -- **Urgencia derivada de Jira:** GhostMap se conecta a Jira, obtiene los tiempos del sprint actual y de sprints dependientes, e identifica —con ayuda de IA— relaciones y dependencias entre sprints para marcar qué Ghosts son urgentes (por vencimiento propio o por bloquear otro sprint). +- **Urgencia derivada de Jira:** GhostMap se conecta a Jira, obtiene los tiempos del sprint actual y de sprints dependientes, e identifica (con ayuda de IA) relaciones y dependencias entre sprints para marcar qué Ghosts son urgentes (por vencimiento propio o por bloquear otro sprint). - **Chat local en VS Code** que resume conversaciones y contexto relevante, y propone qué hacer a continuación según urgencia y alcance. - **Retomar contexto con un click:** el dev entra directo a la primera tarea urgente, o continúa exactamente donde lo dejó el día anterior. - **Ghost Threads (discusiones por bloque de código):** cualquier función, clase o bloque puede tener su propia discusión, con responsable técnico, QA, etc., con permisos configurables, incluyendo comentarios enviados desde Slack hacia una discusión concreta. @@ -60,7 +58,7 @@ Un dev termina su día. Al siguiente, abre VS Code y GhostMap. - **Cierre de tarea automatizado:** al cambiar el status de un Ghost a `done` (o equivalente), GhostMap puede generar el commit correspondiente, actualizar Jira, notificar a QA/revisor, y reflejar el nuevo estado en tiempo real para todo el equipo. - **Permisos y trazabilidad:** dado que esta capa puede generar commits, modificar tickets y crear subtareas automáticamente, Enterprise incluye control de permisos por rol y un registro de qué acción fue tomada por una persona y cuál por un agente de IA. -## Pilar 2 — Entender código ajeno +## Pilar 2: Entender código ajeno Un dev nuevo abre un archivo y no sabe qué hay realmente ahí. diff --git a/docs/status/estado-del-proyecto.md b/docs/status/estado-del-proyecto.md index e162f9f..5ffacb2 100644 --- a/docs/status/estado-del-proyecto.md +++ b/docs/status/estado-del-proyecto.md @@ -6,9 +6,8 @@ sidebar_label: Estado del proyecto # Estado del proyecto -:::caution V1 en pruebas finales -GhostMap V1 tiene buena cobertura de funcionalidad y pruebas automatizadas, pero todavía está pasando por validaciones manuales finales antes de un release amplio. Algunas funciones pueden comportarse de forma ligeramente distinta a lo descrito hasta que esas validaciones terminen. -::: +> **V1 en pruebas finales:** +> GhostMap V1 tiene buena cobertura de funcionalidad y pruebas automatizadas, pero todavía está pasando por validaciones manuales finales antes de un release amplio. Algunas funciones pueden comportarse de forma ligeramente distinta a lo descrito hasta que esas validaciones terminen. ## Estado de distribución @@ -42,8 +41,8 @@ Ningún cambio en estos canales afecta el código que ya tienes instalado por VS ## Advertencias y dirección a futuro - **Idioma del producto (workstream separado):** GhostMap soporta 19 lenguajes hoy. Está planificada una expansión de ~20 lenguajes adicionales, bloqueada por empaquetado y procedencia de los WASM de Tree-sitter, validez de queries y cobertura de fixtures. Esos lenguajes no se anuncian como soportados hasta pasar ese gate. Ver [Requisitos](/get-started/requisitos) y [Disclaimer](/legal/disclaimer). -- **Motor V2 e integraciones Enterprise (no enviado):** la indexación a nivel de workspace, el Ghost Watcher y las integraciones Enterprise (Jira / Slack, Ghost Threads, Ghost Graph, dashboards, explicaciones con IA, permisos / audit log) están diseñadas pero **no publicadas**. Cualquier integración con servicios de servidor requeriría su propio aviso claro de privacidad y consentimiento explícito antes de salir. Ver [Roadmap — Visión v2](/roadmap/vision-v2); para una copia de la Privacy Policy vigente, escribir a [getghostmap@proton.me](mailto:getghostmap@proton.me). +- **Motor V2 e integraciones Enterprise (no enviado):** la indexación a nivel de workspace, el Ghost Watcher y las integraciones Enterprise (Jira / Slack, Ghost Threads, Ghost Graph, dashboards, explicaciones con IA, permisos / audit log) están diseñadas pero **no publicadas**. Cualquier integración con servicios de servidor requeriría su propio aviso claro de privacidad y consentimiento explícito antes de salir. Ver [Roadmap: Visión v2](/roadmap/vision-v2); para una copia de la Privacy Policy vigente, escribir a [getghostmap@proton.me](mailto:getghostmap@proton.me). ## Próximos pasos -Ver **[Roadmap — Visión v2](/roadmap/vision-v2)** para la dirección a más largo plazo del proyecto. +Ver **[Roadmap: Visión v2](/roadmap/vision-v2)** para la dirección a más largo plazo del proyecto. diff --git a/docs/vsix-install.md b/docs/vsix-install.md index 3932e28..27d21ee 100644 --- a/docs/vsix-install.md +++ b/docs/vsix-install.md @@ -6,7 +6,7 @@ sidebar_label: Instalar desde VSIX # Instalar GhostMap desde un archivo VSIX -Hoy el VSIX entregado por contacto directo es el **camino único** de instalación de GhostMap, no solo un fallback. El paquete todavía no está publicado en VS Code Marketplace (falta dar de alta al `publisher`) y Open VSX tiene el script de publicación (`publish:open-vsx`, que invoca `ovsx publish`) ya preparado en `package.json`, pero quedan pendientes el namespace en open-vsx.org, el token y el primer publish. GitHub Releases queda como canal planificado post-tag; todavía no hay release público y el repositorio fuente sigue privado. Mientras tanto, todos los usuarios — incluso quienes están en VS Code estándar — instalan vía VSIX recibido por mail. +Hoy el VSIX entregado por contacto directo es el **camino único** de instalación de GhostMap, no solo un fallback. El paquete todavía no está publicado en VS Code Marketplace (falta dar de alta al `publisher`) y Open VSX tiene el script de publicación (`publish:open-vsx`, que invoca `ovsx publish`) ya preparado en `package.json`, pero quedan pendientes el namespace en open-vsx.org, el token y el primer publish. GitHub Releases queda como canal planificado post-tag; todavía no hay release público y el repositorio fuente sigue privado. Mientras tanto, todos los usuarios (incluso quienes están en VS Code estándar) instalan vía VSIX recibido por mail. Ver el estado de cada canal en **[Instalación → Estado de distribución](/get-started/instalacion)**. @@ -79,7 +79,7 @@ Cuando instalas desde VSIX (que hoy es el modo por defecto): - El extension se marca como "side-loaded" y no aparece en tus extensiones sincronizadas si usas Settings Sync. - En entornos gestionados por IT, puede que la política bloquee instalaciones VSIX. Consulta con tu administrador. -Cuando se publique GhostMap en VS Code Marketplace y Open VSX (ambos están pendientes/planificados — ver [Estado del proyecto](/status/estado-del-proyecto)), los avisos de actualización in-editor y la sincronización de Settings Sync funcionarán de forma estándar. +Cuando se publique GhostMap en VS Code Marketplace y Open VSX (ambos están pendientes/planificados: ver [Estado del proyecto](/status/estado-del-proyecto)), los avisos de actualización in-editor y la sincronización de Settings Sync funcionarán de forma estándar. ## Siguiente paso diff --git a/docusaurus.config.js b/docusaurus.config.js index 935c8a8..1b0504e 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -4,7 +4,7 @@ import {themes as prismThemes} from 'prism-react-renderer'; /** @type {import('@docusaurus/types').Config} */ const config = { title: 'GhostMap', - tagline: 'Estructura de proyecto, dentro de tu código.', + tagline: 'Project structure, inside your code.', favicon: 'img/favicon.svg', future: { @@ -31,8 +31,8 @@ const config = { }, i18n: { - defaultLocale: 'es', - locales: ['es'], + defaultLocale: 'en', + locales: ['en'], }, headTags: [ @@ -95,7 +95,7 @@ const config = { announcementBar: { id: 'v1-prerelease', content: - 'GhostMap V1 está en pre-release. La sintaxis @ghost y los settings son estables, pero pueden ajustarse en versiones futuras antes de la 1.0.', + 'GhostMap V1 is in pre-release. @ghost syntax and settings are stable, but may still change before 1.0.', backgroundColor: '#0e0e1a', textColor: '#eeeef5', isCloseable: true, @@ -108,19 +108,23 @@ const config = { }, items: [ { - type: 'docSidebar', - sidebarId: 'docsSidebar', + to: '/', + label: 'Start', position: 'left', - label: 'Docs', + }, + { + to: '/get-started/instalacion', + position: 'left', + label: 'Spanish details', }, { href: 'mailto:getghostmap@proton.me', - label: 'Contacto', + label: 'Contact', position: 'right', }, { - to: '/get-started/instalacion', - label: 'Instalar (VSIX local)', + to: '/en/install', + label: 'Install', position: 'right', className: 'navbar-cta', }, @@ -130,22 +134,33 @@ const config = { style: 'dark', links: [ { - title: 'Producto', + title: 'Product', items: [ - {label: 'Inicio', to: '/'}, + {label: 'Start', to: '/'}, + {label: 'Install / Access', to: '/en/install'}, + {label: 'Spanish details', to: '/get-started/instalacion'}, {label: 'Roadmap', to: '/roadmap/vision-v2'}, - {label: 'Estado del proyecto', to: '/status/estado-del-proyecto'}, + {label: 'Project status', to: '/status/estado-del-proyecto'}, ], }, { - title: 'Documentación', + title: 'Spanish details', items: [ - {label: 'Guía rápida', to: '/get-started/instalacion'}, + {label: 'Instalación', to: '/get-started/instalacion'}, {label: 'Conceptos', to: '/guide/symbol'}, {label: 'Referencia', to: '/reference/sintaxis'}, {label: 'FAQ', to: '/faq'}, ], }, + { + title: 'English start pages', + items: [ + {label: 'Home', to: '/'}, + {label: 'Overview', to: '/en/overview'}, + {label: 'Install / Access', to: '/en/install'}, + {label: 'Legal & Support', to: '/en/legal-support'}, + ], + }, { title: 'Legal', items: [ @@ -153,15 +168,15 @@ const config = { {label: 'Terms of Use', to: '/legal/terms'}, {label: 'Third-Party Notices', to: '/legal/notices'}, {label: 'Disclaimer', to: '/legal/disclaimer'}, - {label: 'Consultas legales (email)', href: 'mailto:getghostmap@proton.me'}, + {label: 'Legal questions (email)', href: 'mailto:getghostmap@proton.me'}, ], }, { - title: 'Comunidad', + title: 'Community', items: [ {label: 'Support GhostMap', href: 'https://ghostmap-liard.vercel.app/#support'}, {label: 'getghostmap@proton.me', href: 'mailto:getghostmap@proton.me'}, - {label: 'Reportar un bug', href: 'mailto:getghostmap@proton.me'}, + {label: 'Report a bug', href: 'mailto:getghostmap@proton.me'}, ], }, ], diff --git a/sidebars.js b/sidebars.js index 6b51389..9ef6690 100644 --- a/sidebars.js +++ b/sidebars.js @@ -4,13 +4,19 @@ const sidebars = { docsSidebar: [ { - type: 'doc', - id: 'intro', - label: 'Introducción', + type: 'category', + label: 'English start', + collapsed: false, + items: [ + 'intro', + 'en/overview', + 'en/install', + 'en/legal-support', + ], }, { type: 'category', - label: 'Empezar', + label: 'Spanish details', collapsed: false, items: [ 'get-started/requisitos', @@ -21,7 +27,7 @@ const sidebars = { }, { type: 'category', - label: 'Guía / Conceptos', + label: 'Guía / Conceptos (ES)', collapsed: false, items: [ 'guide/philosophy', @@ -39,7 +45,7 @@ const sidebars = { }, { type: 'category', - label: 'Referencia', + label: 'Referencia (ES)', collapsed: false, items: [ 'reference/sintaxis', @@ -52,7 +58,7 @@ const sidebars = { }, { type: 'category', - label: 'Arquitectura', + label: 'Arquitectura (ES)', items: [ 'architecture/arquitectura-v1', 'architecture/loading-policy', @@ -62,7 +68,7 @@ const sidebars = { }, { type: 'category', - label: 'Ayuda', + label: 'Ayuda (ES)', items: [ 'faq', 'troubleshooting', @@ -77,14 +83,14 @@ const sidebars = { }, { type: 'category', - label: 'Roadmap', + label: 'Roadmap (ES)', items: [ 'roadmap/vision-v2', ], }, { type: 'category', - label: 'Estado', + label: 'Estado (ES)', items: [ 'status/estado-del-proyecto', ], diff --git a/src/css/custom.css b/src/css/custom.css index 6f4c9ea..b7fab09 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -1,5 +1,5 @@ /** - * GhostMap Docs — theme tokens + * GhostMap Docs theme tokens * Paleta tomada del landing: fondo casi negro, acentos violeta/morado. */ diff --git a/vercel.json b/vercel.json new file mode 100644 index 0000000..bd6fd8f --- /dev/null +++ b/vercel.json @@ -0,0 +1,3 @@ +{ + "cleanUrls": true +}