MarxWellB · jojosenthusiast · Jun 21, 2026 · Jun 21, 2026 · Jun 22, 2026 · Jun 22, 2026
diff --git 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/<category>/` 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
@@ -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
@@ -13,17 +13,16 @@ 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`.
 
 ## Qué verás si esto te afecta
 
 > "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
@@ -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
@@ -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
@@ -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
@@ -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).