MarxWellB · MarxWellB · Jun 24, 2026 · Jun 21, 2026 · Jun 21, 2026 · Jun 22, 2026
diff --git a/README.md b/README.md
@@ -25,31 +25,37 @@ 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.
 
+Subpage routing relies on `vercel.json` setting `cleanUrls: true` together with `trailingSlash: false` in `docusaurus.config.js`: Docusaurus emits `path/page.html` and Vercel serves it at `/path/page`. If subpages 404 in production while local `build/` contains the file, verify the Vercel project setting **Output Directory** is empty (so `vercel.json`'s `outputDirectory: "build"` applies) and that **Clean URLs** is enabled.
+
 ## Content structure
 
-| Folder | Purpose |
+| Path | 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/changelog.md` | User-visible release notes. |
+| `docs/intro.md` | Root start page (slug `/`). |
+| `docs/overview.md` | Product overview (slug `/overview`). |
+| `docs/install.md` | Install / access (slug `/install`). |
+| `docs/vsix-install.md` | Detailed VSIX install reference. |
+| `docs/get-started/` | Requirements and the first-5-minutes walkthrough. |
+| `docs/guide/` | Concepts: symbols, anchors, ownership, validity gate. |
+| `docs/reference/` | Syntax, Ghost Tree, diagnostics, settings, performance. |
+| `docs/architecture/` | V1 pipeline, loading policy, local state. |
+| `docs/roadmap/` | V2 vision. |
+| `docs/status/` | Project status and known limits. |
+| `docs/legal-support.md` | License summary and support contact (slug `/legal-support`). |
 | `docs/legal/` | Privacy Policy, Terms of Use, Third-Party Notices, Disclaimer. |
+| `docs/changelog.md` | Release notes. |
+| `docs/data-location.md`, `docs/troubleshooting.md`, `docs/faq.md`, `docs/glossary.md`, `docs/keyboard-shortcuts.md`, `docs/uninstall.md` | Standalone reference pages. |
 | `sidebars.js` | Sidebar layout. |
 | `docusaurus.config.js` | Site configuration. |
+| `vercel.json` | Build and redirect config for Vercel. |
 
 ## 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.
-
 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`).
+1. Create the `.md` file under `docs/` (or the appropriate subfolder) with a YAML frontmatter block (`id`, `title`, `sidebar_label`, `slug`).
 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
diff --git a/docs/architecture/loading-policy.md b/docs/architecture/loading-policy.md
@@ -1,30 +1,29 @@
 ---
 id: loading-policy
-title: Loading Policy (archivos grandes)
+title: Loading Policy (large files)
 sidebar_label: Loading Policy
 ---
 
-# Loading Policy (archivos grandes)
+# Loading Policy (large files)
 
-## Problema que resuelve
+## The problem it solves
 
-Sin límites, abrir un archivo enorme (decenas o cientos de miles de líneas) dispararía el pipeline completo de extracción y construcción del árbol en cada apertura o edición, lo que podría congelar la UI del editor.
+Without limits, opening a huge file (tens or hundreds of thousands of lines) would fire the full extraction and tree-building pipeline on every open or edit, which could freeze the editor UI.
 
-## Comportamiento
+## Behavior
 
-- 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 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`.
+- A default budget exists: `ghostmap.loading.maxAutoLines = 60000` (60,000 lines).
+- If a file exceeds that budget, the **automatic refresh** (on open or edit) is skipped by default: no fresh analysis is run.
+- If a **valid prior snapshot** exists in [Local State](/architecture/local-state), it can still be shown (cached/stale UI) even though no recompute happens.
+- The **manual refresh** (`Refresh` button) on a file that exceeds the budget is **also skipped by default**, unless you explicitly enable `ghostmap.loading.allowManualLargeFileRefresh = true`.
 
-## Qué verás si esto te afecta
+## What you will see if this affects you
 
-> "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."
+> "This file has more than 60,000 lines. GhostMap did not recompute the tree automatically to avoid blocking the editor. If the displayed tree looks stale, you can enable `ghostmap.loading.allowManualLargeFileRefresh` and use `Refresh` manually."
 
-:::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.
-:::
+> **Relation to v2:**
+> The [Ghost Index v2](/roadmap/v2) aims to relax this limit with a persistent index and incremental updates, to avoid recomputing whole files on open. Even in V2, budgets, backpressure, and recovery tests will still be needed to protect the Extension Host on extreme files.
 
-## Siguiente paso
+## Next step
 
-Continúa con **[Local State](/architecture/local-state)** para entender la caché de continuidad por workspace.
+Continue with **[Local State](/architecture/local-state)** to understand the per-workspace continuity cache.
diff --git a/docs/architecture/local-state.md b/docs/architecture/local-state.md
@@ -6,18 +6,18 @@ sidebar_label: Local State
 
 # Local State (`.ghostmap/ghostmap.json`)
 
-## Qué es
+## What it is
 
-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.
+A per-workspace local cache that GhostMap keeps in V1, stored in `.ghostmap/ghostmap.json` inside the project. GhostMap remembers the state of your files across sessions for faster loads.
 
-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.
+It is a first (simpler) step toward what the [v2 roadmap](/roadmap/v2) calls the "Ghost Project Index": in V1 it is a per-file continuity cache; in v2 it becomes a full workspace index with relations, an incremental watcher, and analytics.
 
-## Comportamiento
+## Behavior
 
-- 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.
+- On close and reopen of a document, GhostMap can restore the last known state (`ghostmap.json`) instead of recomputing from scratch immediately.
+- **Safety rule:** if the restored data is "stale" (not yet confirmed valid), it is not published as fresh in hover or navigation. The UI may show a provisional view, but GhostMap does not claim that information is up to date until it confirms it.
+- Defensively handled cases: corrupted JSON and unsupported schemas from older file versions. In both cases, GhostMap does not fail and does not show incorrect data as valid.
 
-## Siguiente paso
+## Next step
 
-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)**.
+This is the end of the Architecture section. If you want to know what comes next, continue with **[Roadmap: v2 vision](/roadmap/v2)**.
diff --git a/docs/architecture/v1.md b/docs/architecture/v1.md
@@ -0,0 +1,58 @@
+---
+id: v1
+title: Current architecture (v1 / MVP)
+sidebar_label: Architecture v1
+---
+
+# Current architecture (v1 / MVP)
+
+> **Note:**
+> This section is for curious devs and contributors. It is not required for daily GhostMap use.
+
+## Flow diagram
+
+```text
+Workspace
+   ↓
+Symbol Extraction      (LSP → Tree-sitter → regex/PHP fallback)
+   ↓
+Anchor Parsing         (reads @ghost line comments in the document)
+   ↓
+Ownership Resolution   (attaches contextual metadata to the closest symbol;
+                         detects detached/ambiguous)
+   ↓
+Hierarchy Builder      (tree by range containment)
+   ↓
+Ghost Tree             (filters, search, icons)
+   ↓
+VS Code UI             (Tree View + Hover + Diagnostics + Code Actions)
+```
+
+## When it runs
+
+The full pipeline runs:
+
+- When an editor opens or activates.
+- On every edit, with a small debounce so it does not recompute on every keystroke.
+
+In V1, there is no full cross-session workspace persistence: each file open repeats the computation. The exception is the per-document continuity cache described in [Local State](/architecture/local-state). The [v2 roadmap](/roadmap/v2) plans to eliminate this recompute with a persistent workspace index.
+
+## Data model (`GhostItem`)
+
+```ts
+interface GhostItem {
+  id: string;
+  name: string;
+  type: 'function' | 'class' | 'anchor';
+  range: vscode.Range;
+  endLine?: number;
+  anchorKind?: 'single' | 'range' | 'contextual';
+  description?: string;
+  status?: string;
+  children?: GhostItem[];
+}
+```
+
+## Next step
+
+Continue with **[Loading Policy](/architecture/loading-policy)** to understand how GhostMap handles large files.
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -8,14 +8,16 @@ sidebar_label: Changelog
 
 Every user-visible fix and feature in GhostMap is logged here with the reasoning behind it. This is the product changelog; the round-by-round internal log lives alongside the extension source.
 
+Public history starts at `0.5.0`, the first version stamp shipped outside the maintainers. Earlier work was internal stabilization and is summarized below.
+
 ## 0.5.0 - June 18, 2026
 
 The first version stamp after multiple rounds of stabilization. Marks GhostMap as feature-complete pre-1.0: the Ghost Tree, the Ghost Engine, the Ghost Index, anchors, diagnostics, and status badges all behave as documented.
 
 ### Added
 
 - **Status badges in the Ghost Tree header**: the panel title now shows `[loading]`, `[cached]`, `[stale-cache]`, `[skipped]`, `[no items]`, or `[discarded:...]` so you can see exactly what the engine is doing without opening the console.
-- **Snippet coverage widened to 20 language IDs**: the `gh` / `gw` / `gr` / `gl` / `gxl` / `gxr` prefixes are now available in JavaScript, TypeScript, JSX, TSX, C, C++, C#, Java, Go, Rust, PHP, Kotlin, Swift, Scala, Groovy, Solidity, Python, Ruby, Elixir, and Shell.
+- **Snippet coverage widened to 20 language IDs**: the `gh` / `gw` / `gr` / `gl` / `gxl` / `gxr` prefixes are now available in JavaScript, TypeScript, JSX, TSX, C, C++, C#, Java, Go, Rust, PHP, Kotlin, Swift, Scala, Groovy, Solidity, Python, Ruby, Elixir, and Shell. Snippet availability does not imply Ghost Tree symbol extraction support.
 
 ### Fixed (round 6)
 
@@ -65,4 +67,4 @@ The first version stamp after multiple rounds of stabilization. Marks GhostMap a
 
 ## Next steps
 
-For the V2 vision, see the [Roadmap](/roadmap/vision-v2). For known limitations of the current release, see the [Disclaimer](/legal/disclaimer).
+For known limitations of the current release, see the [Disclaimer](/legal/disclaimer).