Skip to content

AI-native design editor. Open-source Figma alternative.

docs: reorganize documentation and improve integrity

Danila Poyarkov3ef554ab2d54
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index c90084b30..57815ffc0 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -20,7 +20,7 @@ jobs:
- name: Build SDK packages for documentation
run: bun run build:packages
- - run: bun run --filter @open-pencil/docs build
+ - run: bun run --filter @open-pencil/docs build:production
- uses: cloudflare/wrangler-action@v4
with:
diff --git a/AGENTS.md b/AGENTS.md
index 91b2c98da..6f0ab0913 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -17,7 +17,7 @@ Bun workspace packages:
- `packages/vue` — `@open-pencil/vue`: headless Vue 3 SDK (Reka UI-style) for building custom OpenPencil-powered editor shells and embedded editing surfaces. Renderless components and composables. The app is one consumer of the SDK.
- `packages/cli` — `@open-pencil/cli`: headless CLI for .fig inspection, export, linting. Uses `citty` + `agentfmt`.
- `packages/mcp` — `@open-pencil/mcp`: MCP server for AI coding tools. Stdio + HTTP (Hono). Reuses core tools.
-- `packages/docs` — `@open-pencil/docs`: published VitePress documentation site. Run with `bun run docs:dev`.
+- `packages/docs` — `@open-pencil/docs`: published VitePress documentation site. Use `bun run docs:dev` for authoring, `bun run docs:build` for the default fast local render check without minification or generated LLM files, and `bun run docs:build:production` for the complete deployment output.
The root app (`src/`) is the Tauri/Vite desktop editor. App-specific editor, document, AI, collaboration, shell, tabs, demo, and automation code lives under `src/app/*`. The app consumes scene graph primitives from `@open-pencil/scene-graph`, editor/rendering services through targeted `@open-pencil/core` subpath exports, and `@open-pencil/vue` through the public Vue SDK entrypoint.
@@ -102,7 +102,7 @@ Production Cloudflare Pages deploys are intentionally release/manual only: `app.
- `CHANGELOG.md` — all user-facing changes, grouped by version. "Unreleased" section at top for in-progress work.
- `README.md` — user-facing: features, getting started, CLI, project structure. No implementation details.
- `AGENTS.md` (this file) — contributor/agent reference: architecture, conventions, how to release.
-- `packages/docs/` — VitePress site deployed at `openpencil.dev`. User guide, SDK, automation, reference, and development docs. Do not create English placeholder copies under locale directories; until a real translation exists, localized navigation should link to the canonical English page.
+- `packages/docs/` — VitePress site deployed at `openpencil.dev`. Keep its public information architecture explicit: `/getting-started` for installation, `/overview/**` for product overview and comparisons, `/user-guide/**` for editor workflows, `/programmable/**` for automation and SDK docs, `/reference/**` for compatibility and technical reference, and `/development/**` for contributor internals and the roadmap. Do not reintroduce a generic `/guide/**` section. Preserve moved public routes in `packages/docs/public/_redirects`. Do not create English placeholder copies under locale directories; until a real translation exists, localized navigation should link to the canonical English page.
When adding features, update `CHANGELOG.md` (Unreleased section) and `README.md` (if user-facing). Update `AGENTS.md` when architecture or conventions change. Do not put speculative/internal implementation plans in `packages/docs/**`; VitePress docs are published. Keep temporary plans in ignored `scratch/` or distill durable public direction into the canonical roadmap.
diff --git a/README.md b/README.md
index 07ba3cf55..c714a37c7 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@ Open-source design editor. Opens `.fig` and `.pen` design files, includes built-
> **Status:** Active development. Usable today, with some rough edges as features evolve.
-**[Try it online →](https://app.openpencil.dev/demo)** · [Download](https://github.com/open-pencil/open-pencil/releases/latest) · [Documentation](https://openpencil.dev) · [llms.txt](https://openpencil.dev/llms.txt)
+**[Try it online →](https://app.openpencil.dev/demo)** · [Download](https://github.com/open-pencil/open-pencil/releases/latest) · [Documentation](https://openpencil.dev) · [Roadmap](https://openpencil.dev/development/roadmap) · [llms.txt](https://openpencil.dev/llms.txt)
![OpenPencil](packages/docs/public/screenshot.png)
diff --git a/bun.lock b/bun.lock
index 5e5542f03..7a07f00d0 100644
--- a/bun.lock
+++ b/bun.lock
@@ -88,11 +88,14 @@
"@types/ws": "^8.18.1",
"@typescript/native-preview": "^7.0.0-dev.20260228.1",
"@vitejs/plugin-vue": "^6.0.5",
+ "cloudflare-redirect-parser": "^1.0.0",
"esbuild": "^0.27.3",
"fake-indexeddb": "^6.2.5",
"hono": "^4.12.5",
"jscpd": "^4.0.8",
"knip": "6.20.0",
+ "mdast": "^3.0.0",
+ "mdast-util-from-markdown": "^2.0.3",
"mitata": "^1.0.34",
"oxfmt": "^0.35.0",
"oxlint": "^1.50.0",
@@ -104,6 +107,7 @@
"tsdown": "^0.22.3",
"tw-animate-css": "^1.4.0",
"typescript": "~5.8.3",
+ "unist-util-visit": "^5.1.0",
"unplugin-icons": "^23.0.1",
"unplugin-raw": "^0.6.4",
"unplugin-vue": "^7.1.1",
@@ -320,6 +324,9 @@
"canvaskit-wasm",
],
},
+ "tools/docs": {
+ "name": "@open-pencil/docs-tools",
+ },
},
"overrides": {
"brace-expansion": "5.0.6",
@@ -859,6 +866,8 @@
"@open-pencil/docs": ["@open-pencil/docs@workspace:packages/docs"],
+ "@open-pencil/docs-tools": ["@open-pencil/docs-tools@workspace:tools/docs"],
+
"@open-pencil/dom-css": ["@open-pencil/dom-css@workspace:packages/dom-css"],
"@open-pencil/fig": ["@open-pencil/fig@workspace:packages/fig"],
@@ -1605,6 +1614,8 @@
"cliui": ["[email protected]", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.1", "wrap-ansi": "^7.0.0" } }, "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ=="],
+ "cloudflare-redirect-parser": ["[email protected]", "", {}, "sha512-puEB3wmP47RICu/CboTHd237Up/r3Nagsr622mJxWgvEVfRxNlKceNfpPieMYDe/E1nYJsf6iempsrkitgQZVw=="],
+
"color-convert": ["[email protected]", "", { "dependencies": { "color-name": "~1.1.4" } }, "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ=="],
"color-name": ["[email protected]", "", {}, "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA=="],
@@ -2305,6 +2316,8 @@
"math-intrinsics": ["[email protected]", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
+ "mdast": ["[email protected]", "", {}, "sha512-xySmf8g4fPKMeC07jXGz971EkLbWAJ83s4US2Tj9lEdnZ142UP5grN73H1Xd3HzrdbU5o9GYYP/y8F9ZSwLE9g=="],
+
"mdast-util-find-and-replace": ["[email protected]", "", { "dependencies": { "@types/mdast": "^4.0.0", "escape-string-regexp": "^5.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg=="],
"mdast-util-from-markdown": ["[email protected]", "", { "dependencies": { "@types/mdast": "^4.0.0", "@types/unist": "^3.0.0", "decode-named-character-reference": "^1.0.0", "devlop": "^1.0.0", "mdast-util-to-string": "^4.0.0", "micromark": "^4.0.0", "micromark-util-decode-numeric-character-reference": "^2.0.0", "micromark-util-decode-string": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0", "unist-util-stringify-position": "^4.0.0" } }, "sha512-W4mAWTvSlKvf8L6J+VN9yLSqQ9AOAAvHuoDAmPkz4dHf553m5gVj2ejadHJhoJmcmxEnOv6Pa8XJhpxE93kb8Q=="],
diff --git a/package.json b/package.json
index 150cd7098..7aeb50b01 100644
--- a/package.json
+++ b/package.json
@@ -13,7 +13,8 @@
"packages/vue",
"packages/cli",
"packages/mcp",
- "packages/docs"
+ "packages/docs",
+ "tools/docs"
],
"packageManager": "[email protected]",
"type": "module",
@@ -28,8 +29,9 @@
"lint:structure": "oxlint -c oxlint.json vite.config.ts vite/ .storybook/ src/ packages/scene-graph/src/ packages/scene-graph/scripts/ packages/core/src/ packages/vue/src/ packages/cli/src/ packages/mcp/src/ packages/dom-css/src/ packages/dom-css/tests/ packages/dom-css/scripts/ packages/pen/src/ packages/pen/scripts/ packages/kiwi/src/ packages/kiwi/tests/ packages/kiwi/scripts/ packages/fig/src/ packages/fig/tests/ packages/fig/scripts/ tests/ scripts/ tools/",
"format": "oxfmt --write .oxfmtrc.json vite.config.ts vite/ .storybook/ src/ packages/scene-graph/src/ packages/scene-graph/scripts/ packages/core/src/ packages/cli/src/ packages/mcp/src/ packages/vue/src/ packages/dom-css/src/ packages/dom-css/tests/ packages/dom-css/scripts/ packages/pen/src/ packages/pen/scripts/ packages/kiwi/src/ packages/kiwi/tests/ packages/kiwi/scripts/ packages/fig/src/ packages/fig/tests/ packages/fig/scripts/ tests scripts/ tools/",
"format:check": "bun run format && status=$(git status --porcelain -uall) && test -z \"$status\" || (echo \"$status\" && exit 1)",
- "check": "bun run build:packages && bun run lint && tsgo --noEmit && bun run check:vue && bun run check:i18n && bun run check:packages && bun run check:deps && bun run check:audit && bun run check:secrets && bun run check:monorepo && bun run check:arch && bun run test:type-shapes && bun run test:tools && bun run test:dupes",
+ "check": "bun run build:packages && bun run lint && tsgo --noEmit && bun run check:vue && bun run check:i18n && bun run check:docs && bun run check:packages && bun run check:deps && bun run check:audit && bun run check:secrets && bun run check:monorepo && bun run check:arch && bun run test:type-shapes && bun run test:tools && bun run test:dupes",
"check:deps": "knip --include unlisted,unresolved,binaries",
+ "check:docs": "bun --filter @open-pencil/docs check",
"check:audit": "bun audit --audit-level=critical",
"check:secrets": "bun tools/secret-scan/src/index.ts",
"check:monorepo": "sherif --ignore-rule root-package-dependencies",
@@ -53,6 +55,7 @@
"open-pencil": "bun packages/cli/src/index.ts",
"docs:dev": "bun --filter @open-pencil/docs dev",
"docs:build": "bun --filter @open-pencil/docs build",
+ "docs:build:production": "bun --filter @open-pencil/docs build:production",
"docs:preview": "bun --filter @open-pencil/docs preview",
"visual-compare": "bun tools/visual-oracles/src/compare.ts",
"generate:tauri-menu": "bun tools/tauri-menu/src/generate.ts"
@@ -141,11 +144,14 @@
"@types/ws": "^8.18.1",
"@typescript/native-preview": "^7.0.0-dev.20260228.1",
"@vitejs/plugin-vue": "^6.0.5",
+ "cloudflare-redirect-parser": "^1.0.0",
"esbuild": "^0.27.3",
"fake-indexeddb": "^6.2.5",
"hono": "^4.12.5",
"jscpd": "^4.0.8",
"knip": "6.20.0",
+ "mdast": "^3.0.0",
+ "mdast-util-from-markdown": "^2.0.3",
"mitata": "^1.0.34",
"oxfmt": "^0.35.0",
"oxlint": "^1.50.0",
@@ -157,6 +163,7 @@
"tsdown": "^0.22.3",
"tw-animate-css": "^1.4.0",
"typescript": "~5.8.3",
+ "unist-util-visit": "^5.1.0",
"unplugin-icons": "^23.0.1",
"unplugin-raw": "^0.6.4",
"unplugin-vue": "^7.1.1",
diff --git a/packages/docs/.vitepress/config.ts b/packages/docs/.vitepress/config.ts
index 4c7cd1ef4..63e24d465 100644
--- a/packages/docs/.vitepress/config.ts
+++ b/packages/docs/.vitepress/config.ts
@@ -11,6 +11,23 @@ import { rootThemeConfig } from './root-theme'
import { BASE, LOCALE_PREFIXES, applyPageSeo, siteHead, withAlternateSitemapLinks } from './seo'
const repoRoot = fileURLToPath(new URL('../../..', import.meta.url))
+const fastBuild = process.env.OPENPENCIL_DOCS_FAST_BUILD === '1'
+
+const llmsPlugin = llmstxt({
+ domain: BASE,
+ ignoreFiles: LOCALE_PREFIXES.map((locale) => `${locale}/**`),
+ generateLLMsTxt: !fastBuild,
+ generateLLMsFullTxt: !fastBuild,
+ generateLLMFriendlyDocsForEachPage: !fastBuild,
+ injectLLMHint: false,
+ customTemplateVariables: {
+ title: 'OpenPencil',
+ description:
+ 'Open-source, AI-native design editor and toolkit. Opens Figma .fig files, provides a programmable scene graph, CLI, MCP server, and Vue SDK for custom editor shells.',
+ details:
+ 'Use this file as the compact map for agents. For complete Markdown content, fetch https://openpencil.dev/llms-full.txt.'
+ }
+})
export default defineConfig({
title: 'OpenPencil',
@@ -22,7 +39,7 @@ export default defineConfig({
sitemap: {
hostname: BASE,
- transformItems: withAlternateSitemapLinks,
+ transformItems: withAlternateSitemapLinks
},
head: siteHead,
@@ -32,6 +49,9 @@ export default defineConfig({
markdown: {
codeTransformers: [
transformerTwoslash({
+ typesCache: createFileSystemTypesCache({
+ dir: fileURLToPath(new URL('./cache/twoslash', import.meta.url))
+ }),
twoslashOptions: {
compilerOptions: {
baseUrl: repoRoot,
@@ -39,10 +59,7 @@ export default defineConfig({
'@open-pencil/vue': ['packages/vue/src/index.ts'],
'#vue/*': ['packages/vue/src/*']
}
- },
- typesCache: createFileSystemTypesCache({
- dir: fileURLToPath(new URL('./cache/twoslash', import.meta.url))
- })
+ }
}
})
]
@@ -55,25 +72,10 @@ export default defineConfig({
'#vue': fileURLToPath(new URL('../../vue/src', import.meta.url))
}
},
- plugins: [
- tailwindcss(),
- llmstxt({
- domain: BASE,
- ignoreFiles: LOCALE_PREFIXES.map((locale) => `${locale}/**`),
- generateLLMFriendlyDocsForEachPage: true,
- injectLLMHint: false,
- customTemplateVariables: {
- title: 'OpenPencil',
- description:
- 'Open-source, AI-native design editor and toolkit. Opens Figma .fig files, provides a programmable scene graph, CLI, MCP server, and Vue SDK for custom editor shells.',
- details:
- 'Use this file as the compact map for agents. For complete Markdown content, fetch https://openpencil.dev/llms-full.txt.'
- }
- })
- ]
+ plugins: [tailwindcss(), llmsPlugin]
},
locales: docsLocales,
- themeConfig: rootThemeConfig(),
+ themeConfig: rootThemeConfig()
})
diff --git a/packages/docs/.vitepress/labels.ts b/packages/docs/.vitepress/labels.ts
index 9f7de2e68..dd1e1849a 100644
--- a/packages/docs/.vitepress/labels.ts
+++ b/packages/docs/.vitepress/labels.ts
@@ -8,13 +8,14 @@ export interface SidebarLabels {
shapes: string
text: string
pen: string
+ vectorEditing: string
layers: string
contextMenu: string
exporting: string
autoLayout: string
components: string
variables: string
- guide: string
+ overview: string
gettingStarted: string
features: string
architecture: string
@@ -37,7 +38,7 @@ export interface ProgrammableLabels {
}
export interface NavLabels {
- guide: string
+ overview: string
userGuide: string
programmable: string
sdk: string
@@ -141,13 +142,14 @@ export const EN: SidebarLabels = {
shapes: 'Drawing Shapes',
text: 'Text Editing',
pen: 'Pen Tool',
+ vectorEditing: 'Vector Editing',
layers: 'Layers & Pages',
contextMenu: 'Context Menu',
exporting: 'Exporting',
autoLayout: 'Auto Layout',
components: 'Components',
variables: 'Variables',
- guide: 'Guide',
+ overview: 'Overview',
gettingStarted: 'Getting Started',
features: 'Features',
architecture: 'Architecture',
@@ -165,13 +167,14 @@ export const DE: SidebarLabels = {
shapes: 'Formen zeichnen',
text: 'Textbearbeitung',
pen: 'Stiftwerkzeug',
+ vectorEditing: 'Vektorbearbeitung',
layers: 'Ebenen & Seiten',
contextMenu: 'Kontextmenü',
exporting: 'Exportieren',
autoLayout: 'Auto-Layout',
components: 'Komponenten',
variables: 'Variablen',
- guide: 'Anleitung',
+ overview: 'Überblick',
gettingStarted: 'Erste Schritte',
features: 'Funktionen',
architecture: 'Architektur',
@@ -189,13 +192,14 @@ export const IT: SidebarLabels = {
shapes: 'Disegno forme',
text: 'Modifica testo',
pen: 'Strumento penna',
+ vectorEditing: 'Modifica vettoriale',
layers: 'Livelli e pagine',
contextMenu: 'Menu contestuale',
exporting: 'Esportazione',
autoLayout: 'Auto-layout',
components: 'Componenti',
variables: 'Variabili',
- guide: 'Guida',
+ overview: 'Panoramica',
gettingStarted: 'Per iniziare',
features: 'Funzionalità',
architecture: 'Architettura',
@@ -213,13 +217,14 @@ export const FR: SidebarLabels = {
shapes: 'Dessiner des formes',
text: 'Édition de texte',
pen: 'Outil plume',
+ vectorEditing: 'Édition vectorielle',
layers: 'Calques et pages',
contextMenu: 'Menu contextuel',
exporting: 'Exportation',
autoLayout: 'Mise en page auto',
components: 'Composants',
variables: 'Variables',
- guide: 'Guide',
+ overview: 'Vue d’ensemble',
gettingStarted: 'Premiers pas',
features: 'Fonctionnalités',
architecture: 'Architecture',
@@ -237,13 +242,14 @@ export const ES: SidebarLabels = {
shapes: 'Dibujar formas',
text: 'Edición de texto',
pen: 'Herramienta pluma',
+ vectorEditing: 'Edición vectorial',
layers: 'Capas y páginas',
contextMenu: 'Menú contextual',
exporting: 'Exportar',
autoLayout: 'Auto-layout',
components: 'Componentes',
variables: 'Variables',
- guide: 'Guía',
+ overview: 'Resumen',
gettingStarted: 'Primeros pasos',
features: 'Características',
architecture: 'Arquitectura',
@@ -261,13 +267,14 @@ export const PL: SidebarLabels = {
shapes: 'Rysowanie kształtów',
text: 'Edycja tekstu',
pen: 'Narzędzie pióro',
+ vectorEditing: 'Edycja wektorów',
layers: 'Warstwy i strony',
contextMenu: 'Menu kontekstowe',
exporting: 'Eksportowanie',
autoLayout: 'Auto-layout',
components: 'Komponenty',
variables: 'Zmienne',
- guide: 'Przewodnik',
+ overview: 'Przegląd',
gettingStarted: 'Rozpoczęcie pracy',
features: 'Funkcje',
architecture: 'Architektura',
@@ -285,13 +292,14 @@ export const RU: SidebarLabels = {
shapes: 'Рисование фигур',
text: 'Редактирование текста',
pen: 'Инструмент «Перо»',
+ vectorEditing: 'Редактирование векторов',
layers: 'Слои и страницы',
contextMenu: 'Контекстное меню',
exporting: 'Экспорт',
autoLayout: 'Авто-раскладка',
components: 'Компоненты',
variables: 'Переменные',
- guide: 'Руководство',
+ overview: 'Обзор',
gettingStarted: 'Начало работы',
features: 'Возможности',
architecture: 'Архитектура',
diff --git a/packages/docs/.vitepress/locale-theme.ts b/packages/docs/.vitepress/locale-theme.ts
index f2e44b76d..b63e3a4df 100644
--- a/packages/docs/.vitepress/locale-theme.ts
+++ b/packages/docs/.vitepress/locale-theme.ts
@@ -16,23 +16,24 @@ export const localeThemeConfig = (
sidebar: SidebarLabels,
prog: ProgrammableLabels,
): DefaultTheme.Config => ({
+ // Not every canonical page has a maintained translation. Locale switches return
+ // to the locale home instead of inventing a corresponding URL that may 404.
+ i18nRouting: false,
nav: [
- { text: nav.guide, link: `${prefix}/guide/getting-started` },
+ { text: nav.overview, link: `${prefix}/getting-started` },
{ text: nav.userGuide, link: `${prefix}/user-guide/` },
{ text: nav.programmable, link: `${prefix}/programmable/` },
{ text: nav.sdk, link: `${prefix}/programmable/sdk/` },
{ text: nav.reference, link: `${prefix}/reference/keyboard-shortcuts` },
- { text: nav.development, link: `${prefix}/development/contributing` },
+ { text: nav.development, link: '/development/contributing' },
{ text: nav.openApp, link: 'https://app.openpencil.dev' },
],
sidebar: {
[`${prefix}/user-guide/`]: userGuideSidebar(prefix, sidebar),
[`${prefix}/programmable/sdk/`]: sdkSidebar(prefix),
[`${prefix}/programmable/`]: programmableSidebar(prefix, prog),
- [`${prefix}/reference/`]: referenceSidebar(prefix, nav.reference),
- [`${prefix}/`]: [
- ...guideSidebar(prefix, sidebar),
- ...developmentSidebar(prefix, nav.development),
- ],
+ [`${prefix}/reference/`]: referenceSidebar(prefix, nav.reference, sidebar),
+ [`${prefix}/development/`]: developmentSidebar('', nav.development, sidebar),
+ [`${prefix}/`]: guideSidebar(prefix, sidebar),
},
})
diff --git a/packages/docs/.vitepress/locales.ts b/packages/docs/.vitepress/locales.ts
index 97fc5698d..86bf3cec7 100644
--- a/packages/docs/.vitepress/locales.ts
+++ b/packages/docs/.vitepress/locales.ts
@@ -26,7 +26,7 @@ export const docsLocales = {
themeConfig: localeThemeConfig(
'/de',
{
- guide: 'Guide',
+ overview: 'Überblick',
userGuide: 'Benutzerhandbuch',
programmable: 'Automation',
sdk: 'SDK',
@@ -45,7 +45,7 @@ export const docsLocales = {
themeConfig: localeThemeConfig(
'/it',
{
- guide: 'Guida',
+ overview: 'Panoramica',
userGuide: 'Guida utente',
programmable: 'Automation',
sdk: 'SDK',
@@ -64,7 +64,7 @@ export const docsLocales = {
themeConfig: localeThemeConfig(
'/fr',
{
- guide: 'Guide',
+ overview: 'Vue d’ensemble',
userGuide: 'Guide utilisateur',
programmable: 'Automation',
sdk: 'SDK',
@@ -83,7 +83,7 @@ export const docsLocales = {
themeConfig: localeThemeConfig(
'/es',
{
- guide: 'Guía',
+ overview: 'Resumen',
userGuide: 'Guía del usuario',
programmable: 'Automation',
sdk: 'SDK',
@@ -102,7 +102,7 @@ export const docsLocales = {
themeConfig: localeThemeConfig(
'/pl',
{
- guide: 'Przewodnik',
+ overview: 'Przegląd',
userGuide: 'Podręcznik',
programmable: 'Automation',
sdk: 'SDK',
@@ -121,7 +121,7 @@ export const docsLocales = {
themeConfig: localeThemeConfig(
'/ru',
{
- guide: 'Руководство',
+ overview: 'Обзор',
userGuide: 'Руководство',
programmable: 'Automation',
sdk: 'SDK',
diff --git a/packages/docs/.vitepress/root-theme.ts b/packages/docs/.vitepress/root-theme.ts
index c3838fc9a..94fdbdc19 100644
--- a/packages/docs/.vitepress/root-theme.ts
+++ b/packages/docs/.vitepress/root-theme.ts
@@ -1,6 +1,7 @@
import { EN, EN_PROG } from './labels'
import { sdkSidebar } from './sdk-sidebar'
import {
+ developmentSidebar,
guideSidebar,
programmableSidebar,
referenceSidebar,
@@ -13,7 +14,7 @@ export const rootThemeConfig = (): DefaultTheme.Config => ({
search: { provider: 'local' },
nav: [
- { text: 'Guide', link: '/guide/getting-started' },
+ { text: 'Overview', link: '/getting-started' },
{ text: 'User Guide', link: '/user-guide/' },
{ text: 'Automation', link: '/programmable/' },
{ text: 'SDK', link: '/programmable/sdk/' },
@@ -26,18 +27,9 @@ export const rootThemeConfig = (): DefaultTheme.Config => ({
'/user-guide/': userGuideSidebar('', EN),
'/programmable/sdk/': sdkSidebar(''),
'/programmable/': programmableSidebar('', EN_PROG),
- '/reference/': referenceSidebar('', 'Reference'),
- '/': [
- ...guideSidebar('', EN),
- {
- text: 'Development',
- items: [
- { text: 'Contributing', link: '/development/contributing' },
- { text: 'Testing', link: '/development/testing' },
- { text: 'Roadmap', link: '/development/roadmap' },
- ],
- },
- ],
+ '/reference/': referenceSidebar('', 'Reference', EN),
+ '/development/': developmentSidebar('', 'Development', EN),
+ '/': guideSidebar('', EN),
},
socialLinks: [{ icon: 'github', link: 'https://github.com/open-pencil/open-pencil' }],
diff --git a/packages/docs/.vitepress/sdk-sidebar.ts b/packages/docs/.vitepress/sdk-sidebar.ts
index a3ca25527..d325ddcde 100644
--- a/packages/docs/.vitepress/sdk-sidebar.ts
+++ b/packages/docs/.vitepress/sdk-sidebar.ts
@@ -9,6 +9,7 @@ const SDK_COMPONENT_PAGES = [
{ text: 'ToolbarItem', slug: 'toolbar-item' },
{ text: 'PageListRoot', slug: 'page-list-root' },
{ text: 'PropertySection', slug: 'property-section', canonical: true },
+ { text: 'PropertyGrid', slug: 'property-grid', canonical: true },
{ text: 'SegmentedControl', slug: 'segmented-control', canonical: true },
{ text: 'PropertyListRoot', slug: 'property-list-root' },
{ text: 'PropertyListItem', slug: 'property-list-item' },
@@ -52,8 +53,11 @@ const SDK_COMPOSABLE_PAGES = [
{ text: 'useFillControls', slug: 'use-fill-controls' },
{ text: 'useStrokeControls', slug: 'use-stroke-controls' },
{ text: 'useEffectsControls', slug: 'use-effects-controls' },
+ { text: 'useMask', slug: 'use-mask', canonical: true },
+ { text: 'useDocumentWorkspace', slug: 'use-document-workspace', canonical: true },
{ text: 'useVariablesEditor', slug: 'use-variables-editor' },
- { text: 'usePageList', slug: 'use-page-list' }
+ { text: 'usePageList', slug: 'use-page-list' },
+ { text: 'useI18n', slug: 'use-i18n' },
] as const
const SDK_ADVANCED_PAGES = [
@@ -75,7 +79,13 @@ const SDK_ADVANCED_PAGES = [
{ text: 'useLayerTree', slug: 'use-layer-tree' },
{ text: 'useToolbar', slug: 'use-toolbar' },
{ text: 'usePropertyList', slug: 'use-property-list' },
- { text: 'useNumberField', slug: 'use-number-field' }
+ { text: 'useNumberField', slug: 'use-number-field' },
+ { text: 'useOkHCL', slug: 'use-okhcl' },
+ { text: 'useVariables', slug: 'use-variables' },
+ { text: 'useVariablesDialogState', slug: 'use-variables-dialog-state' },
+ { text: 'useVariablesTable', slug: 'use-variables-table' },
+ { text: 'Locale APIs', slug: 'locale-apis' },
+ { text: 'useViewportKind', slug: 'use-viewport-kind' },
] as const
export const sdkSidebar = (prefix: string): DefaultTheme.SidebarItem[] => [
diff --git a/packages/docs/.vitepress/seo.ts b/packages/docs/.vitepress/seo.ts
index 5f4b5130e..19b7001ed 100644
--- a/packages/docs/.vitepress/seo.ts
+++ b/packages/docs/.vitepress/seo.ts
@@ -1,5 +1,11 @@
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
export const BASE = 'https://openpencil.dev'
+const docsRoot = fileURLToPath(new URL('..', import.meta.url))
+
export const LOCALE_PREFIXES = ['de', 'fr', 'es', 'it', 'pl', 'ru'] as const
export const LOCALES: Record<string, { hreflang: string; ogLocale: string; prefix: string }> = {
@@ -62,16 +68,31 @@ function localizedUrl(slug: string, prefix: string): string {
return `${BASE}${prefix || ''}`
}
+function availableLocalesForPage(relativePath: string) {
+ const canonicalPath = stripLocalePrefix(relativePath)
+
+ return Object.values(LOCALES).filter((locale) => {
+ const localeDirectory = locale.prefix.replace(/^\//, '')
+ return existsSync(resolve(docsRoot, localeDirectory, canonicalPath))
+ })
+}
+
export function withAlternateSitemapLinks<T extends SitemapItem>(items: T[]): T[] {
+ const linksBySlug = new Map<string, Array<{ lang: string; url: string }>>()
+
+ for (const item of items) {
+ const path = new URL(item.url, BASE).pathname.replace(/^\//, '')
+ const slug = slugForPath(path)
+ const localeKey = localeKeyForPath(path)
+ const locale = LOCALES[localeKey]
+ const links = linksBySlug.get(slug) ?? []
+ links.push({ lang: locale.hreflang, url: new URL(item.url, BASE).href })
+ linksBySlug.set(slug, links)
+ }
+
return items.map((item) => {
- const slug = slugForPath(item.url)
- return {
- ...item,
- links: Object.values(LOCALES).map((locale) => {
- const url = slug ? `${BASE}${locale.prefix}/${slug}` : `${BASE}${locale.prefix || '/'}`
- return { lang: locale.hreflang, url }
- })
- }
+ const path = new URL(item.url, BASE).pathname.replace(/^\//, '')
+ return { ...item, links: linksBySlug.get(slugForPath(path)) }
})
}
@@ -89,20 +110,18 @@ export function applyPageSeo(pageData: PageDataLike): void {
head.push(['meta', { property: 'og:url', content: pageUrl }])
head.push(['meta', { property: 'og:locale', content: locale.ogLocale }])
- for (const [key, loc] of Object.entries(LOCALES)) {
- if (key !== localeKey) {
- head.push(['meta', { property: 'og:locale:alternate', content: loc.ogLocale }])
+ for (const localeOption of availableLocalesForPage(pageData.relativePath)) {
+ if (localeOption.prefix !== locale.prefix) {
+ head.push(['meta', { property: 'og:locale:alternate', content: localeOption.ogLocale }])
}
- }
- for (const localeOption of Object.values(LOCALES)) {
head.push([
'link',
{
rel: 'alternate',
hreflang: localeOption.hreflang,
- href: localizedUrl(slug, localeOption.prefix)
- }
+ href: localizedUrl(slug, localeOption.prefix),
+ },
])
}
head.push(['link', { rel: 'alternate', hreflang: 'x-default', href: enSlug }])
diff --git a/packages/docs/.vitepress/sidebars.ts b/packages/docs/.vitepress/sidebars.ts
index 826adf7e7..b8521b24e 100644
--- a/packages/docs/.vitepress/sidebars.ts
+++ b/packages/docs/.vitepress/sidebars.ts
@@ -3,14 +3,11 @@ import type { DefaultTheme } from 'vitepress'
export const guideSidebar = (prefix: string, labels: SidebarLabels): DefaultTheme.SidebarItem[] => [
{
- text: labels.guide,
+ text: labels.overview,
items: [
- { text: labels.gettingStarted, link: `${prefix}/guide/getting-started` },
- { text: labels.features, link: `${prefix}/guide/features` },
- { text: labels.architecture, link: `${prefix}/guide/architecture` },
- { text: labels.techStack, link: `${prefix}/guide/tech-stack` },
- { text: labels.comparison, link: `${prefix}/guide/comparison` },
- { text: labels.figmaMatrix, link: `${prefix}/guide/figma-comparison` },
+ { text: labels.gettingStarted, link: `${prefix}/getting-started` },
+ { text: labels.features, link: `${prefix}/overview/features` },
+ { text: labels.comparison, link: `${prefix}/overview/comparison` },
],
},
]
@@ -33,6 +30,7 @@ export const userGuideSidebar = (
{ text: labels.shapes, link: `${prefix}/user-guide/drawing-shapes` },
{ text: labels.text, link: `${prefix}/user-guide/text-editing` },
{ text: labels.pen, link: `${prefix}/user-guide/pen-tool` },
+ { text: labels.vectorEditing, link: `${prefix}/user-guide/vector-edit` },
],
},
{
@@ -81,7 +79,11 @@ export const programmableSidebar = (
},
]
-export const referenceSidebar = (prefix: string, label: string): DefaultTheme.SidebarItem[] => [
+export const referenceSidebar = (
+ prefix: string,
+ label: string,
+ labels: SidebarLabels,
+): DefaultTheme.SidebarItem[] => [
{
text: label,
items: [
@@ -89,21 +91,32 @@ export const referenceSidebar = (prefix: string, label: string): DefaultTheme.Si
{ text: 'CLI', link: `${prefix}/reference/cli` },
{ text: 'Node Types', link: `${prefix}/reference/node-types` },
{ text: 'Scene Graph', link: `${prefix}/reference/scene-graph` },
- { text: 'DOM/CSS Mapping', link: `${prefix}/reference/dom-css-mapping` },
+ { text: labels.figmaMatrix, link: `${prefix}/reference/figma-compatibility` },
+ ...(!prefix ? [{ text: 'DOM/CSS Mapping', link: '/reference/dom-css-mapping' }] : []),
{ text: 'File Format', link: `${prefix}/reference/file-format` },
],
},
]
-export const developmentSidebar = (prefix: string, label: string): DefaultTheme.SidebarItem[] => [
+export const developmentSidebar = (
+ prefix: string,
+ label: string,
+ labels: SidebarLabels,
+): DefaultTheme.SidebarItem[] => [
{
text: label,
items: [
{ text: 'Contributing', link: `${prefix}/development/contributing` },
{ text: 'Testing', link: `${prefix}/development/testing` },
- { text: 'Roadmap', link: `${prefix}/development/roadmap` },
- { text: 'Renderer Profiler', link: `${prefix}/development/renderer-profiler` },
- { text: 'Vector Conversion', link: `${prefix}/development/vector-conversion` },
+ { text: labels.architecture, link: `${prefix}/development/architecture` },
+ { text: labels.techStack, link: `${prefix}/development/tech-stack` },
+ ...(!prefix
+ ? [
+ { text: 'Roadmap', link: '/development/roadmap' },
+ { text: 'Renderer Profiler', link: '/development/renderer-profiler' },
+ { text: 'Vector Conversion', link: '/development/vector-conversion' },
+ ]
+ : []),
],
},
]
diff --git a/packages/docs/de/development/contributing.md b/packages/docs/de/development/contributing.md
deleted file mode 100644
index e3d602ba3..000000000
--- a/packages/docs/de/development/contributing.md
+++ /dev/null
@@ -1,90 +0,0 @@
-# Mitwirken
-
-## Projektstruktur
-
-```
-packages/
- core/ @open-pencil/core — Engine (keine DOM-Abhängigkeiten)
- src/ Szenengraph, Renderer, Layout, Codec, Kiwi, Typen
- cli/ @open-pencil/cli — Headless-CLI für .fig-Operationen
- src/commands/ info, tree, find, export, eval, analyze
- mcp/ @open-pencil/mcp — MCP-Server für KI-Werkzeuge
- src/ stdio + HTTP (Hono) Transporte, 87 Werkzeuge
-src/
- components/ Vue SFCs (Canvas, Panels, Werkzeugleiste, Farbauswahl)
- properties/ Eigenschaftspanel-Abschnitte
- composables/ Canvas-Input, Tastenkürzel, Rendering-Hooks
- stores/ Editor-Zustand (Vue-Reaktivität)
- engine/ Re-Export-Shims von @open-pencil/core
-desktop/ Tauri v2 (Rust + Konfiguration)
-tests/
- e2e/ Playwright visuelle Regression
- engine/ Unit-Tests (bun:test)
-packages/docs/ VitePress-Dokumentationsseite
- specs/ Fähigkeitsspezifikationen (Wahrheitsquelle)
- changes/ Aktive und archivierte Änderungen
-```
-
-## Entwicklungsumgebung
-
-```sh
-bun install
-bun run dev # Editor auf localhost:1420
-bun run docs:dev # Dokumentation auf localhost:5173
-```
-
-## Code-Stil
-
-### Werkzeuge
-
-| Werkzeug | Befehl | Zweck |
-|----------|--------|-------|
-| oxlint | `bun run lint` | Linting (Rust-basiert, schnell) |
-| oxfmt | `bun run format` | Code-Formatierung |
-| tsgo | `bun run typecheck` | Typprüfung (Go-basierter TypeScript-Prüfer) |
-
-Alle Prüfungen ausführen:
-
-```sh
-bun run check
-```
-
-### Konventionen
-
-- **Dateinamen** — kebab-case (`scene-graph.ts`, `use-canvas-input.ts`)
-- **Komponenten** — PascalCase Vue SFCs (`EditorCanvas.vue`, `NumberField.vue`)
-- **Konstanten** — SCREAMING_SNAKE_CASE
-- **Funktionen/Variablen** — camelCase
-- **Typen/Interfaces** — PascalCase
-
-### KI-Agent-Konventionen
-
-Entwickler und KI-Agenten sollten `AGENTS.md` im Repo-Root lesen ([auf GitHub ansehen](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)). Behandelt Rendering, Szenengraph, Komponenten & Instanzen, Layout, UI, Dateiformat, Tauri-Konventionen und bekannte Probleme.
-
-## Änderungen vornehmen
-
-1. Änderung implementieren
-2. `bun run check` und `bun run test` ausführen
-3. Pull Request einreichen
-
-## Schlüsseldateien
-
-Der Core-Engine-Quellcode lebt in `packages/core/src/`. App-spezifischer Editor-, Dokument-, KI-, Kollaborations-, Shell-, Demo- und Automatisierungscode liegt unter `src/app/*`; das Vue SDK verwaltet wiederverwendbaren Canvas- und Composable-Code unter `packages/vue/src/`.
-
-| Datei | Zweck |
-|-------|-------|
-| `packages/scene-graph/src/` | Szenengraph: Knoten, Variablen, Instanzen, Hit-Testing und Undo |
-| `packages/core/src/canvas/renderer.ts` | CanvasKit-Rendering-Pipeline |
-| `packages/core/src/layout/` | Yoga-Layout-Adapter |
-| `packages/core/src/clipboard.ts` | Figma-kompatible Zwischenablage |
-| `packages/core/src/vector/` | Vektornetzwerk-Modell |
-| `packages/kiwi/src/schema-runtime/` | Kiwi-Schema-Runtime und Binär-Codec |
-| `packages/fig/src/node-change/` | SceneGraph- und Figma-NodeChange-Konvertierung |
-| `packages/core/src/io/formats/fig/` | App-seitige .fig-Lese-/Schreiborchestrierung |
-| `packages/core/src/tools/` | Vereinheitlichte Werkzeugdefinitionen (KI, MCP, CLI) |
-| `packages/core/src/figma-api/` | Figma Plugin API-Implementierung |
-| `packages/mcp/src/server.ts` | MCP-Server-Factory |
-| `packages/cli/src/index.ts` | CLI-Einstiegspunkt |
-| `src/app/editor/session/create.ts` | Editor session assembly |
-| `packages/vue/src/canvas/CanvasRoot.vue` | Canvas-Rendering-Composable |
-| `src/app/shell/keyboard/use.ts` | Tastenkürzel-Behandlung |
diff --git a/packages/docs/de/development/testing.md b/packages/docs/de/development/testing.md
deleted file mode 100644
index 65bb63308..000000000
--- a/packages/docs/de/development/testing.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# Testen
-
-## Übersicht
-
-| Type | Framework | Command | Location |
-|------|-----------|---------|----------|
-| E2E visual regression | Playwright | `bun run test` | `tests/e2e/` |
-| Figma CDP reference | Playwright | `bun run test:figma` | `tests/figma/` |
-| Unit tests | bun:test | `bun run test:unit` | `tests/engine/` |
-
-## E2E Visuelle Regression
-
-```sh
-bun run test # Compare against baselines
-bun run test:update # Regenerate baselines
-```
-
-1. Playwright → headless browser
-2. `data-ready` HTML attribute
-3. Create shapes → screenshot → `toMatchSnapshot`
-
-## Figma CDP-Referenztests
-
-```sh
-bun run figma:debug # Launch Figma with debugging port
-bun run test:figma # Connect via CDP
-```
-
-## Unit-Tests
-
-```sh
-bun run test:unit
-```
-
-- Scene graph CRUD, hit testing
-- Fig-import pipeline
-- Layout computation (Yoga)
-- MCP server edge cases
-
-## E2E-Testabdeckung
-
-| Test file | Scope |
-|-----------|-------|
-| `tests/e2e/layers-panel.spec.ts` | Layers panel |
-| `tests/e2e/visual.spec.ts` | Visual regression |
-
-## Leistungsziele
-
-| Metric | Target |
-|--------|--------|
-| E2E suite | < 3s |
-| Unit tests | < 50ms |
diff --git a/packages/docs/de/guide/getting-started.md b/packages/docs/de/getting-started.md
similarity index 93%
rename from packages/docs/de/guide/getting-started.md
rename to packages/docs/de/getting-started.md
index ffdb98ef7..9397f1ab9 100644
--- a/packages/docs/de/guide/getting-started.md
+++ b/packages/docs/de/getting-started.md
@@ -50,7 +50,8 @@ bun run dev
| `bun run test:update` | Screenshot-Baselines erneuern |
| `bun run test:unit` | Unit-Tests (bun:test) |
| `bun run docs:dev` | Dokumentations-Entwicklungsserver |
-| `bun run docs:build` | Dokumentationsseite bauen |
+| `bun run docs:build` | Schneller lokaler Dokumentations-Build |
+| `bun run docs:build:production` | Vollständigen deploybaren Dokumentations-Build erstellen |
## Desktop-App (Tauri)
diff --git a/packages/docs/de/guide/architecture.md b/packages/docs/de/guide/architecture.md
deleted file mode 100644
index 30dba745d..000000000
--- a/packages/docs/de/guide/architecture.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# Architektur
-
-## Systemübersicht
-
-`mermaid
-graph TB
- subgraph Tauri["Tauri v2 Shell"]
- subgraph Editor["Editor (Web)"]
- UI["Vue 3 UI<br/>Toolbar · Panels · Properties<br/>Layers · Color Picker"]
- Skia["Skia CanvasKit (WASM, 7MB)<br/>Vector rendering · Text shaping<br/>Effects · Export"]
- subgraph Core["Core Engine (TS)"]
- SG[SceneGraph] --- Layout[Layout - Yoga]
- SG --- Selection
- Undo[Undo/Redo] --- Constraints
- Constraints --- HitTest[Hit Testing]
- end
- subgraph FileFormat["File Format Layer"]
- FigIO[".fig import/export"] --- Kiwi[Kiwi codec]
- Kiwi --- SVG[SVG export]
- end
- end
- MCP["MCP Server (90 tools, stdio+HTTP)"]
- Collab["P2P Collab (Trystero + Yjs)"]
- end
-`
-
-## Editor-Layout
-
-Die Oberfläche folgt Figmas UI3-Layout — Werkzeugleiste unten, Navigation links, Eigenschaften rechts:
-
-- **Navigationspanel (links)** — Ebenenbaum, Seitenpanel
-- **Canvas (Mitte)** — Unendlicher Canvas mit CanvasKit-Rendering, Zoom/Pan
-- **Eigenschaftspanel (rechts)** — Kontextsensitive Abschnitte: Darstellung, Füllung, Kontur, Typografie, Layout, Position
-- **Werkzeugleiste (unten)** — Werkzeugauswahl: Auswahl, Frame, Sektion, Rechteck, Ellipse, Linie, Text, Stift, Hand
-
-## Komponenten
-
-### Rendering (CanvasKit WASM)
-
-Dieselbe Rendering-Engine wie Figma. CanvasKit bietet GPU-beschleunigte 2D-Zeichnung mit Vektorformen, Textgestaltung via Paragraph API, Effekten (Schatten, Unschärfe, Mischmodi) und Export (PNG, SVG). Das 7 MB große WASM-Binary wird beim Start geladen und erstellt eine GPU-Oberfläche auf dem HTML-Canvas.
-
-Der Renderer ist in fokussierte Module in `packages/core/src/renderer/` aufgeteilt: Szenentraversierung, Overlays, Füllungen, Konturen, Formen, Effekte, Lineale, Labels und Remote-Cursor.
-
-### Szenengraph
-
-Flache `Map<string, Node>` mit GUID-Strings als Schlüssel. Baumstruktur über `parentIndex`-Referenzen. Bietet O(1)-Lookup, effiziente Traversierung, Hit-Testing und rechteckige Bereichsabfragen für Marquee-Selektion.
-
-Der Graph emittiert typisierte Events über nanoevents: `node:created`, `node:updated`, `node:deleted`, `node:reparented`, `node:reordered`. Subsysteme abonnieren diese anstelle manueller Verdrahtung — der Editor nutzt sie für Render-Invalidierung und Microtask-gebatchte Komponenten-Instanz-Synchronisation, das Collab-System für Yjs-Propagierung.
-
-Siehe [Szenengraph-Referenz](/reference/scene-graph) für Interna.
-
-### Layout-Engine (Yoga WASM)
-
-Metas Yoga bietet CSS-Flexbox- und Grid-Layout-Berechnung über einen [Fork](https://github.com/open-pencil/yoga/tree/grid) mit CSS-Grid-Unterstützung. Ein dünner Adapter mappt Figma-Eigenschaftsnamen auf Yoga-Äquivalente:
-
-| Figma-Eigenschaft | Yoga-Äquivalent |
-|---|---|
-| `stackMode: HORIZONTAL` | `flexDirection: row` |
-| `stackMode: VERTICAL` | `flexDirection: column` |
-| `stackSpacing` | `gap` |
-| `stackPadding` | `padding` |
-| `stackJustify` | `justifyContent` |
-| `stackChildPrimaryGrow` | `flexGrow` |
-
-### Dateiformat (Kiwi-Binär)
-
-Verwendet Figmas Kiwi-Binär-Codec mit 194 Message-/Enum-/Struct-Definitionen. Import: Header parsen → Zstd-Dekompression → Kiwi-Dekodierung → `NodeChange`[] → Szenengraph. Export kehrt den Prozess um, inklusive Thumbnail-Generierung.
-
-Siehe [Dateiformat-Referenz](/reference/file-format) für Details.
-
-### KI & Werkzeuge
-
-Werkzeuge werden einmal in `packages/core/src/tools/` definiert, aufgeteilt nach Domäne: read, create, modify, structure, variables, vector, analyze. Jedes Werkzeug hat typisierte Parameter und eine `execute(figma, args)`-Funktion. Adapter konvertieren sie für:
-
-- **KI-Chat** — valibot-Schemas, Multi-Provider (Anthropic, OpenAI, Google AI, OpenRouter, kompatible Endpunkte)
-- **MCP-Server** — zod-Schemas, stdio + HTTP-Transporte
-- **CLI** — verfügbar über den `eval`-Befehl
-
-90+ Core-Werkzeuge + 3 MCP-Dateiverwaltungswerkzeuge. Enthält XPath-Abfrage (`query_nodes`), JSX-Inspektion (`get_jsx`, `diff_jsx`), semantische Beschreibung (`describe`) und visionsbasierte Überprüfung (`export_image` gibt Bilder an das Modell zurück).
-
-### Rückgängig/Wiederherstellen
-
-Inverse-Command-Muster. Vor jeder Änderung werden betroffene Felder als Snapshot gespeichert. Der Snapshot wird zur inversen Operation. Batching gruppiert schnelle Änderungen (wie Ziehen) zu einzelnen Undo-Einträgen.
-
-### Zwischenablage
-
-Figma-kompatible bidirektionale Zwischenablage. Kodiert/dekodiert Kiwi-Binär (gleiches Format wie .fig-Dateien) über native Browser-Kopier/Einfüge-Events. Verarbeitet Vektorpfad-Skalierung, Instanz-Kinder, Component-Set-Erkennung und Override-Anwendung.
-
-### P2P-Kollaboration
-
-Echtzeit-Peer-to-Peer-Kollaboration über Trystero (WebRTC) + Yjs CRDT. Kein Server-Relay — Signalisierung über öffentliche MQTT-Broker, STUN/TURN für NAT-Traversal. Das Awareness-Protokoll bietet Live-Cursor, Auswahlen und Präsenz. Lokale Persistenz über y-indexeddb.
-
-### CLI-zu-App RPC-Bridge
-
-Wenn die Desktop-App läuft, verbinden sich CLI-Befehle über WebSocket statt eine .fig-Datei zu benötigen. Der Automatisierungsserver läuft auf `127.0.0.1:7600` (HTTP) und `127.0.0.1:7601` (WebSocket). Befehle werden gegen den Live-Editor-Zustand ausgeführt, sodass Automatisierungsskripte und KI-Agenten mit der laufenden App interagieren können.
-
-## Ausblick
-
-### Vollständiges figma-use-Werkzeugset
-
-Der MCP-Server bietet derzeit 90 Werkzeuge. Die Referenzimplementierung in [figma-use](https://github.com/dannote/figma-use) hat 118. Die verbleibenden Werkzeuge decken erweiterte Layout-Constraints, Prototyp-Verbindungen, erweiterte Komponenteneigenschafts-Bearbeitung und Massen-Dokumentoperationen ab.
-
-### CI-Design-Werkzeuge
-
-Die headless CLI unterstützt bereits `analyze colors/typography/spacing/clusters`. Nächster Schritt: GitHub Actions-Integration für automatisiertes Design-Linting und visuelle Regression in PRs.
-
-### Prototyping
-
-Frame-zu-Frame-Übergänge, Interaktions-Trigger (Klick, Hover, Ziehen), Overlay-Verwaltung und Vollbild-Vorschaumodus.
-
-### Windows Code Signing
-
-macOS-Binaries sind seit v0.6.0 signiert und notarisiert. Windows Authenticode-Signierung über Azure Code Signing ist geplant, um die SmartScreen-Warnung zu entfernen.
diff --git a/packages/docs/de/guide/tech-stack.md b/packages/docs/de/guide/tech-stack.md
deleted file mode 100644
index 0c0c9fd18..000000000
--- a/packages/docs/de/guide/tech-stack.md
+++ /dev/null
@@ -1,67 +0,0 @@
-# Tech-Stack
-
-## Kerntechnologien
-
-| Schicht | Technologie | Warum |
-|---------|-----------|-------|
-| **Rendering** | Skia CanvasKit WASM | Dieselbe Engine wie Figma — bewährte Leistung, GPU-beschleunigt, pixelgenau |
-| **UI-Framework** | Vue 3 + VueUse | Reaktive Composition API, hervorragende TypeScript-Unterstützung |
-| **Komponenten** | Reka UI | Headless, barrierefreie UI-Primitive (Tree, Slider usw.) |
-| **Styling** | Tailwind CSS 4 | Utility-first, schnelle Iteration, dunkles Theme |
-| **Layout** | Yoga WASM | CSS-Flexbox-Engine von Meta, kampferprobt in React Native |
-| **Dateiformat** | Kiwi-Binär + Zstd | Figmas eigenes Format — kompakt, schnelles Parsen, .fig-kompatibel |
-| **Kollaboration** | Trystero + Yjs | P2P-WebRTC über MQTT-Signalisierung, CRDT-Sync, y-indexeddb-Persistenz |
-| **Farbe** | culori | Farbraum-Konvertierungen (HSV, RGB, Hex) |
-| **KI/MCP** | MCP SDK + Hono | 90+ Tools für KI-Coding-Werkzeuge, stdio- + HTTP-Transporte |
-| **JSX-Transform** | Sucrase | 201 KB JSX → JS, synchron, browser-kompatibel |
-| **Events** | nanoevents | 108 Bytes, typisierter Event-Emitter für SceneGraph-Mutationen |
-| **Desktop** | Tauri v2 | ~5 MB native App (vs. Electrons ~100 MB), Rust-Backend |
-| **Build** | Vite 7 | Schnelles HMR, native ES-Module |
-| **Testing** | Playwright + bun:test | Visuelle Regression (E2E) + schnelle Unit-Tests |
-| **Linting** | oxlint | Rust-basiert, um Größenordnungen schneller als ESLint |
-| **Formatierung** | oxfmt | Rust-basierter Formatierer |
-| **Typprüfung** | typescript-go (tsgo) | Native Go-Implementierung des TypeScript-Typprüfers |
-
-## Wichtige Abhängigkeiten
-
-```json
-{
- "canvaskit-wasm": "^0.40.0",
- "vue": "^3.5.29",
- "yoga-layout": "npm:@open-pencil/[email protected]",
- "nanoevents": "^9.1.0",
- "sucrase": "^3.35.1",
- "reka-ui": "^2.8.2",
- "tailwindcss": "^4.2.1",
- "culori": "^4.0.2",
- "fzstd": "^0.1.1",
- "fflate": "^0.8.2",
- "trystero": "^0.20.0",
- "yjs": "^13.6.24",
- "y-indexeddb": "^9.0.12"
-}
-```
-
-## Warum nicht...
-
-### Warum kein SVG-Rendering?
-
-SVG ist langsam für komplexe Dokumente. Jeder Knoten ist ein DOM-Element — 10.000 Knoten bedeuten 10.000 DOM-Knoten. CanvasKit zeichnet alles auf eine einzige GPU-Oberfläche.
-
-### Warum nicht Electron (wie Figma Desktop)?
-
-Tauri v2 nutzt den System-Webview (~5 MB) statt Chromium zu bündeln (~100 MB).
-
-### Warum nicht React?
-
-Das Projekt migrierte früh von React zu Vue 3. Vues Reaktivitätssystem und VueUse-Composables erwiesen sich als ergonomischer.
-
-### Warum keine eigene Layout-Engine?
-
-Yoga wird von Meta gepflegt, ist auf Milliarden von React-Native-Geräten getestet und implementiert die CSS-Flexbox-Spezifikation.
-
-## Zusätzliche Technologien
-
-| Technologie | Zweck | Status |
-|-----------|---------|--------|
-| CSS Grid in Yoga | Grid-basiertes Auto-Layout | Unterstützt über [Yoga-Fork](https://github.com/open-pencil/yoga/tree/grid) (`@open-pencil/yoga-layout`) |
diff --git a/packages/docs/de/guide/comparison.md b/packages/docs/de/overview/comparison.md
similarity index 97%
rename from packages/docs/de/guide/comparison.md
rename to packages/docs/de/overview/comparison.md
index 5dcee2bc1..f46d17d4d 100644
--- a/packages/docs/de/guide/comparison.md
+++ b/packages/docs/de/overview/comparison.md
@@ -77,7 +77,7 @@ Open Pencil und Penpot verwenden beide Skia für das Rendering, aber die Impleme
| | Open Pencil | Penpot |
|---|-------------|--------|
| CLI | ✅ Headless .fig-Operationen | ❌ Kein CLI |
-| AI-Werkzeuge | **87 Werkzeuge** + MCP-Server | Plugin-System |
+| KI-Werkzeuge | **90+ Werkzeuge** + MCP-Server | Plugin-System |
| JSX-Renderer | ✅ Programmgesteuerte Erstellung | ❌ |
| Eval-Befehl | ✅ Figma Plugin API | ❌ |
| Plugin-System | Über eval/MCP | ✅ Natives Plugin-System |
@@ -97,7 +97,7 @@ Open Pencil und Penpot verwenden beide Skia für das Rendering, aber die Impleme
| | Open Pencil | Penpot |
|---|-------------|--------|
| Integrierter Chat | ✅ OpenRouter-Integration | ❌ |
-| Werkzeugnutzung | 87 Design-Werkzeuge | ❌ |
+| Werkzeugnutzung | 90+ Design-Werkzeuge | ❌ |
| MCP-Server | ✅ stdio + HTTP | ❌ |
| Bring your own key | ✅ Kein Vendor-Lock-in | ❌ |
diff --git a/packages/docs/de/guide/features.md b/packages/docs/de/overview/features.md
similarity index 100%
rename from packages/docs/de/guide/features.md
rename to packages/docs/de/overview/features.md
diff --git a/packages/docs/de/programmable/index.md b/packages/docs/de/programmable/index.md
index aab66641a..36e9e61e5 100644
--- a/packages/docs/de/programmable/index.md
+++ b/packages/docs/de/programmable/index.md
@@ -12,7 +12,7 @@ Die Editor-Oberfläche und die Automatisierungsschnittstellen verwenden dieselbe
## KI-Chat
-Der integrierte Assistent hat Zugriff auf 87 Werkzeuge, die die gesamte Oberfläche des Editors abdecken. Beschreibe in natürlicher Sprache, was du möchtest — „füge allen Buttons einen 16px Schlagschatten hinzu", „erstelle eine Kartenkomponente mit Dark-Mode-Variante", „exportiere jeden Frame auf dieser Seite in 2×".
+Der integrierte Assistent hat Zugriff auf mehr als 90 Werkzeuge, die die gesamte Oberfläche des Editors abdecken. Beschreibe in natürlicher Sprache, was du möchtest — „füge allen Buttons einen 16px Schlagschatten hinzu", „erstelle eine Kartenkomponente mit Dark-Mode-Variante", „exportiere jeden Frame auf dieser Seite in 2×".
[KI-Chat →](./ai-chat)
diff --git a/packages/docs/de/guide/figma-comparison.md b/packages/docs/de/reference/figma-compatibility.md
similarity index 99%
rename from packages/docs/de/guide/figma-comparison.md
rename to packages/docs/de/reference/figma-compatibility.md
index a0f6c2414..ea7402519 100644
--- a/packages/docs/de/guide/figma-comparison.md
+++ b/packages/docs/de/reference/figma-compatibility.md
@@ -215,7 +215,7 @@ Feature-für-Feature-Vergleich der Figma-Design-Funktionen mit dem aktuellen Imp
| Code Connect | 🔲 | Design-Komponenten mit Code verknüpfen |
| Code-Snippets | 🟡 | JSX-Export mit Hervorhebung und Kopieren; keine CSS/Swift/Kotlin-Snippets |
| Figma für VS Code | 🔲 | Editor-Plugin-Integration |
-| MCP-Server | ✅ | @open-pencil/mcp mit stdio + HTTP-Transporten; 87 Kern-Werkzeuge + 3 Dateiverwaltung = 90 gesamt |
+| MCP-Server | ✅ | @open-pencil/mcp mit stdio- und HTTP-Transporten sowie mehr als 90 Werkzeugen einschließlich Dateioperationen |
| CLI-Werkzeuge | ✅ | Headless-CLI: info, tree, find, export, analyze, node, pages, variables, eval; MCP-Server |
## Figma Draw
diff --git a/packages/docs/guide/architecture.md b/packages/docs/development/architecture.md
similarity index 100%
rename from packages/docs/guide/architecture.md
rename to packages/docs/development/architecture.md
diff --git a/packages/docs/guide/tech-stack.md b/packages/docs/development/tech-stack.md
similarity index 100%
rename from packages/docs/guide/tech-stack.md
rename to packages/docs/development/tech-stack.md
diff --git a/packages/docs/es/development/contributing.md b/packages/docs/es/development/contributing.md
deleted file mode 100644
index b7cb06af1..000000000
--- a/packages/docs/es/development/contributing.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# Contribuir
-
-## Estructura del proyecto
-
-```
-packages/
- core/ @open-pencil/core — motor (sin deps DOM)
- src/ Grafo de escena, renderer, layout, codec, kiwi, tipos
- cli/ @open-pencil/cli — CLI headless para operaciones .fig
- src/commands/ info, tree, find, export, eval, analyze
- mcp/ @open-pencil/mcp — servidor MCP para herramientas IA
- src/ Transportes stdio + HTTP (Hono), 87 herramientas
-src/
- components/ Vue SFCs (canvas, paneles, barra de herramientas, selector de color)
- properties/ Secciones del panel de propiedades (Apariencia, Relleno, Trazo, etc.)
- composables/ Entrada de canvas, atajos de teclado, hooks de renderizado
- stores/ Estado del editor (reactividad Vue)
- engine/ Shims de re-exportación desde @open-pencil/core
- kiwi/ Shims de re-exportación desde @open-pencil/core
- types.ts Tipos compartidos (re-exportados desde core)
- constants.ts Colores UI, valores por defecto, umbrales
-desktop/ Tauri v2 (Rust + config)
-tests/
- e2e/ Regresión visual Playwright
- engine/ Tests unitarios (bun:test)
-docs/ Sitio de documentación VitePress
- specs/ Especificaciones de capacidades (fuente de verdad)
- changes/ Cambios activos y archivados
-```
-
-## Entorno de desarrollo
-
-```sh
-bun install
-bun run dev # Editor en localhost:1420
-bun run docs:dev # Docs en localhost:5173
-```
-
-## Estilo de código
-
-### Herramientas
-
-| Herramienta | Comando | Propósito |
-|-------------|---------|-----------|
-| oxlint | `bun run lint` | Linting (basado en Rust, rápido) |
-| oxfmt | `bun run format` | Formateo de código |
-| tsgo | `bun run typecheck` | Verificación de tipos (checker TypeScript basado en Go) |
-
-Ejecutar todas las verificaciones:
-
-```sh
-bun run check
-```
-
-### Convenciones
-
-- **Nombres de archivo** — kebab-case (`scene-graph.ts`, `use-canvas-input.ts`)
-- **Componentes** — PascalCase Vue SFCs (`EditorCanvas.vue`, `NumberField.vue`)
-- **Constantes** — SCREAMING_SNAKE_CASE
-- **Funciones/variables** — camelCase
-- **Tipos/interfaces** — PascalCase
-
-### Convenciones para agentes IA
-
-Desarrolladores y agentes IA deben leer `AGENTS.md` en la raíz del repo ([ver en GitHub](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)). Cubre renderizado, grafo de escena, componentes e instancias, layout, UI, formato de archivo, convenciones Tauri y problemas conocidos.
-
-## Realizar cambios
-
-3. Implementar el cambio
-4. Ejecutar `bun run check` y `bun run test`
-5. Enviar un pull request
-
-## Archivos clave
-
-El código fuente del motor core vive en `packages/core/src/`. El código específico de la app para editor, documentos, IA, colaboración, shell, demo y automatización vive en `src/app/*`; el SDK Vue contiene el código reutilizable de canvas y composables en `packages/vue/src/`.
-
-| Archivo | Propósito |
-|---------|-----------|
-| `packages/scene-graph/src/` | Grafo de escena: nodos, variables, instancias, hit testing y deshacer |
-| `packages/core/src/canvas/renderer.ts` | Pipeline de renderizado CanvasKit |
-| `packages/core/src/layout/` | Adaptador de layout Yoga |
-| `packages/core/src/clipboard.ts` | Portapapeles compatible con Figma |
-| `packages/core/src/vector/` | Modelo de red vectorial |
-| `packages/core/src/io/formats/raster/render.ts` | Exportación de imagen offscreen (PNG/JPG/WEBP) |
-| `packages/kiwi/src/schema-runtime/` | Runtime de esquema y códec binario Kiwi |
-| `packages/fig/src/node-change/` | Política de conversión entre SceneGraph y Figma NodeChange |
-| `packages/core/src/io/formats/fig/` | Orquestación de lectura/escritura .fig para la app |
-| `packages/cli/src/index.ts` | Punto de entrada del CLI |
-| `packages/core/src/tools/` | Definiciones unificadas de herramientas (IA, MCP, CLI) |
-| `packages/core/src/figma-api/` | Implementación de Figma Plugin API |
-| `packages/mcp/src/server.ts` | Factory del servidor MCP |
-| `packages/cli/src/commands/` | Comandos CLI (info, tree, find, export, eval, analyze) |
-| `src/app/editor/session/create.ts` | Editor session assembly |
-| `packages/vue/src/canvas/CanvasRoot.vue` | Composable de renderizado del canvas |
-| `packages/vue/src/canvas/useCanvasInput.ts` | Manejo de entrada ratón/touch |
-| `src/app/shell/keyboard/use.ts` | Manejo de atajos de teclado |
diff --git a/packages/docs/es/development/testing.md b/packages/docs/es/development/testing.md
deleted file mode 100644
index 7b40a0ee4..000000000
--- a/packages/docs/es/development/testing.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# Pruebas
-
-## Visión general
-
-| Type | Framework | Command | Location |
-|------|-----------|---------|----------|
-| E2E visual regression | Playwright | `bun run test` | `tests/e2e/` |
-| Figma CDP reference | Playwright | `bun run test:figma` | `tests/figma/` |
-| Unit tests | bun:test | `bun run test:unit` | `tests/engine/` |
-
-## Regresión visual E2E
-
-```sh
-bun run test # Compare against baselines
-bun run test:update # Regenerate baselines
-```
-
-1. Playwright → headless browser
-2. `data-ready` HTML attribute
-3. Create shapes → screenshot → `toMatchSnapshot`
-
-## Tests de referencia Figma CDP
-
-```sh
-bun run figma:debug # Launch Figma with debugging port
-bun run test:figma # Connect via CDP
-```
-
-## Tests unitarios
-
-```sh
-bun run test:unit
-```
-
-- Scene graph CRUD, hit testing
-- Fig-import pipeline
-- Layout computation (Yoga)
-- MCP server edge cases
-
-## Cobertura de tests E2E
-
-| Test file | Scope |
-|-----------|-------|
-| `tests/e2e/layers-panel.spec.ts` | Layers panel |
-| `tests/e2e/visual.spec.ts` | Visual regression |
-
-## Objetivos de rendimiento
-
-| Metric | Target |
-|--------|--------|
-| E2E suite | < 3s |
-| Unit tests | < 50ms |
diff --git a/packages/docs/es/guide/getting-started.md b/packages/docs/es/getting-started.md
similarity index 91%
rename from packages/docs/es/guide/getting-started.md
rename to packages/docs/es/getting-started.md
index 7ce9d7031..65855c768 100644
--- a/packages/docs/es/guide/getting-started.md
+++ b/packages/docs/es/getting-started.md
@@ -39,4 +39,4 @@ Abre el editor en `http://localhost:1420`.
## Aplicación de escritorio (Tauri)
-Consulta la [versión en inglés](/guide/getting-started) para instrucciones detalladas por plataforma.
+Consulta la [versión en inglés](/getting-started) para instrucciones detalladas por plataforma.
diff --git a/packages/docs/es/guide/architecture.md b/packages/docs/es/guide/architecture.md
deleted file mode 100644
index 78d70a646..000000000
--- a/packages/docs/es/guide/architecture.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# Arquitectura
-
-## Vista general del sistema
-
-`mermaid
-graph TB
- subgraph Tauri["Tauri v2 Shell"]
- subgraph Editor["Editor (Web)"]
- UI["Vue 3 UI<br/>Toolbar · Panels · Properties<br/>Layers · Color Picker"]
- Skia["Skia CanvasKit (WASM, 7MB)<br/>Vector rendering · Text shaping<br/>Effects · Export"]
- subgraph Core["Core Engine (TS)"]
- SG[SceneGraph] --- Layout[Layout - Yoga]
- SG --- Selection
- Undo[Undo/Redo] --- Constraints
- Constraints --- HitTest[Hit Testing]
- end
- subgraph FileFormat["File Format Layer"]
- FigIO[".fig import/export"] --- Kiwi[Kiwi codec]
- Kiwi --- SVG[SVG export]
- end
- end
- MCP["MCP Server (90 tools, stdio+HTTP)"]
- Collab["P2P Collab (Trystero + Yjs)"]
- end
-`
-
-## Diseño del editor
-
-La interfaz sigue el layout UI3 de Figma — barra de herramientas abajo, navegación a la izquierda, propiedades a la derecha:
-
-- **Panel de navegación (izquierda)** — Árbol de capas, panel de páginas
-- **Canvas (centro)** — Canvas infinito con renderizado CanvasKit, zoom/pan
-- **Panel de propiedades (derecha)** — Secciones contextuales: Apariencia, Relleno, Trazo, Tipografía, Layout, Posición
-- **Barra de herramientas (abajo)** — Selección de herramienta: Seleccionar, Frame, Sección, Rectángulo, Elipse, Línea, Texto, Pluma, Mano
-
-## Componentes
-
-### Renderizado (CanvasKit WASM)
-
-El mismo motor de renderizado que Figma. CanvasKit proporciona dibujo 2D acelerado por GPU con formas vectoriales, modelado de texto vía Paragraph API, efectos (sombras, desenfoques, modos de mezcla) y exportación (PNG, SVG). El binario WASM de 7 MB se carga al inicio y crea una superficie GPU en el canvas HTML.
-
-El renderer está dividido en módulos enfocados en `packages/core/src/renderer/`: recorrido de escena, overlays, rellenos, trazos, formas, efectos, reglas, etiquetas y cursores remotos.
-
-### Grafo de escena
-
-`Map<string, Node>` plano con cadenas GUID como claves. Estructura de árbol vía referencias `parentIndex`. Proporciona búsqueda O(1), recorrido eficiente, hit testing y consultas de área rectangular para selección por marquesina.
-
-El grafo emite eventos tipados mediante nanoevents: `node:created`, `node:updated`, `node:deleted`, `node:reparented`, `node:reordered`. Los subsistemas se suscriben a estos en lugar de cableado manual — el editor los usa para invalidación de render y sincronización de instancias de componentes con microtask batching, y el sistema de colaboración para propagación Yjs.
-
-Véase [Referencia del grafo de escena](/reference/scene-graph) para los detalles internos.
-
-### Motor de layout (Yoga WASM)
-
-Yoga de Meta proporciona cálculo de layout CSS flexbox y grid a través de un [fork](https://github.com/open-pencil/yoga/tree/grid) con soporte CSS Grid. Un adaptador delgado mapea nombres de propiedades de Figma a equivalentes de Yoga:
-
-| Propiedad Figma | Equivalente Yoga |
-|---|---|
-| `stackMode: HORIZONTAL` | `flexDirection: row` |
-| `stackMode: VERTICAL` | `flexDirection: column` |
-| `stackSpacing` | `gap` |
-| `stackPadding` | `padding` |
-| `stackJustify` | `justifyContent` |
-| `stackChildPrimaryGrow` | `flexGrow` |
-
-### Formato de archivo (Kiwi binario)
-
-Reutiliza el códec binario Kiwi de Figma con 194 definiciones de mensaje/enum/struct. Importación: parsear cabecera → descomprimir Zstd → decodificar Kiwi → `NodeChange`[] → grafo de escena. La exportación invierte el proceso con generación de miniatura.
-
-Véase [Referencia del formato de archivo](/reference/file-format) para más detalles.
-
-### IA y herramientas
-
-Las herramientas se definen una vez en `packages/core/src/tools/`, divididas por dominio: read, create, modify, structure, variables, vector, analyze. Cada herramienta tiene parámetros tipados y una función `execute(figma, args)`. Los adaptadores las convierten para:
-
-- **Chat IA** — schemas valibot, multi-proveedor (Anthropic, OpenAI, Google AI, OpenRouter, endpoints compatibles)
-- **Servidor MCP** — schemas zod, transportes stdio + HTTP
-- **CLI** — disponibles vía el comando `eval`
-
-90+ herramientas core + 3 herramientas de gestión de archivos MCP. Incluye consulta XPath (`query_nodes`), inspección JSX (`get_jsx`, `diff_jsx`), descripción semántica (`describe`) y verificación visual (`export_image` devuelve imágenes al modelo).
-
-### Deshacer/Rehacer
-
-Patrón de comando inverso. Antes de aplicar cualquier cambio, se captura un snapshot de los campos afectados. El snapshot se convierte en la operación inversa. El batching agrupa cambios rápidos (como arrastre) en entradas de deshacer únicas.
-
-### Portapapeles
-
-Portapapeles bidireccional compatible con Figma. Codifica/decodifica binario Kiwi (mismo formato que archivos .fig) usando eventos nativos de copiar/pegar del navegador. Gestiona escalado de rutas vectoriales, hijos de instancia, detección de conjuntos de componentes y aplicación de overrides.
-
-### Colaboración P2P
-
-Colaboración peer-to-peer en tiempo real vía Trystero (WebRTC) + Yjs CRDT. Sin servidor relay — señalización a través de brokers MQTT públicos, STUN/TURN para traversal NAT. El protocolo de awareness proporciona cursores en vivo, selecciones y presencia. Persistencia local vía y-indexeddb.
-
-### Puente RPC CLI-a-App
-
-Cuando la app de escritorio está en ejecución, los comandos CLI se conectan a ella vía WebSocket en lugar de requerir un archivo .fig. El servidor de automatización corre en `127.0.0.1:7600` (HTTP) y `127.0.0.1:7601` (WebSocket). Los comandos se ejecutan contra el estado del editor en vivo, permitiendo que scripts de automatización y agentes IA interactúen con la app en ejecución.
-
-## Próximos pasos
-
-### Conjunto completo de herramientas figma-use
-
-El servidor MCP actualmente expone 90 herramientas. La implementación de referencia en [figma-use](https://github.com/dannote/figma-use) tiene 118. Las herramientas restantes cubren restricciones de layout avanzadas, conexiones de prototipos, edición avanzada de propiedades de componentes y operaciones masivas de documentos.
-
-### Herramientas de diseño para CI
-
-El CLI headless ya soporta `analyze colors/typography/spacing/clusters`. Próximo: integración con GitHub Actions para linting de diseño automatizado y regresión visual en PRs.
-
-### Prototipado
-
-Transiciones entre frames, triggers de interacción (clic, hover, arrastre), gestión de overlays y modo de vista previa a pantalla completa.
-
-### Firma de código en Windows
-
-Los binarios de macOS están firmados y notarizados desde la v0.6.0. La firma Authenticode de Windows vía Azure Code Signing está planificada para eliminar la advertencia de SmartScreen.
diff --git a/packages/docs/es/guide/tech-stack.md b/packages/docs/es/guide/tech-stack.md
deleted file mode 100644
index 73066e9d9..000000000
--- a/packages/docs/es/guide/tech-stack.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# Stack tecnológico
-
-## Tecnologías principales
-
-| Capa | Tecnología | Por qué |
-|------|-----------|---------|
-| **Renderizado** | Skia CanvasKit WASM | Mismo motor que Figma — rendimiento probado, acelerado por GPU, píxel-perfecto |
-| **Framework UI** | Vue 3 + VueUse | API de composición reactiva, excelente soporte TypeScript |
-| **Componentes** | Reka UI | Primitivas UI headless y accesibles (tree, slider, etc.) |
-| **Estilado** | Tailwind CSS 4 | Utility-first, iteración rápida, tema oscuro |
-| **Layout** | Yoga WASM | Motor CSS flexbox de Meta, probado en React Native |
-| **Formato de archivo** | Kiwi binario + Zstd | Formato propio de Figma — compacto, parseo rápido, compatible con .fig |
-| **Colaboración** | Trystero + Yjs | P2P WebRTC vía señalización MQTT, sync CRDT, persistencia y-indexeddb |
-| **Color** | culori | Conversiones de espacio de color (HSV, RGB, hex) |
-| **IA/MCP** | MCP SDK + Hono | 90+ herramientas para codificación IA, transportes stdio + HTTP |
-| **JSX Transform** | Sucrase | 201 KB JSX → JS, síncrono, compatible con navegador |
-| **Eventos** | nanoevents | 108 bytes, emisor de eventos tipado para mutaciones de SceneGraph |
-| **JSX Transform** | Sucrase | 201 KB JSX → JS, síncrono, compatible con navegador |
-| **Eventos** | nanoevents | 108 bytes, emisor de eventos tipado para mutaciones de SceneGraph |
-| **Desktop** | Tauri v2 | ~5 MB app nativa (vs ~100 MB de Electron), backend Rust |
-| **Build** | Vite 7 | HMR rápido, módulos ES nativos |
-| **Testing** | Playwright + bun:test | Regresión visual (E2E) + tests unitarios rápidos |
-| **Linting** | oxlint | Basado en Rust, órdenes de magnitud más rápido que ESLint |
-| **Formateo** | oxfmt | Formateador basado en Rust |
-| **Verificación de tipos** | typescript-go (tsgo) | Implementación nativa en Go del verificador de tipos TypeScript |
-
-## Dependencias principales
-
-```json
-{
- "canvaskit-wasm": "^0.40.0",
- "vue": "^3.5.29",
- "yoga-layout": "npm:@open-pencil/[email protected]",
- "nanoevents": "^9.1.0",
- "sucrase": "^3.35.1",
- "reka-ui": "^2.8.2",
- "tailwindcss": "^4.2.1",
- "culori": "^4.0.2",
- "fzstd": "^0.1.1",
- "fflate": "^0.8.2",
- "trystero": "^0.20.0",
- "yjs": "^13.6.24",
- "y-indexeddb": "^9.0.12"
-}
-```
-
-## ¿Por qué no...
-
-### ¿Por qué no renderizado SVG?
-
-SVG es lento para documentos complejos. Cada nodo es un elemento DOM — 10.000 nodos significan 10.000 elementos DOM con overhead de layout, pintado y composición. CanvasKit dibuja todo en una única superficie GPU.
-
-### ¿Por qué no Electron (como Figma desktop)?
-
-Tauri v2 usa el webview del sistema (~5 MB) en lugar de empaquetar Chromium (~100 MB). El backend Rust proporciona rendimiento nativo para E/S de archivos e integración con el sistema.
-
-### ¿Por qué no React?
-
-El proyecto migró de React a Vue 3 tempranamente. El sistema de reactividad de Vue y los composables de VueUse resultaron más ergonómicos.
-
-### ¿Por qué no un motor de layout propio?
-
-Yoga es mantenido por Meta, probado en miles de millones de dispositivos React Native e implementa la especificación CSS flexbox.
-
-## Tecnologías planificadas
-
-| Tecnología | Propósito | Fase |
-|-----------|---------|-------|
-| CSS Grid en Yoga | Auto layout basado en grid | ✅ Incluido vía [fork de Yoga](https://github.com/open-pencil/yoga/tree/grid) (`@open-pencil/yoga-layout`) |
diff --git a/packages/docs/es/guide/comparison.md b/packages/docs/es/overview/comparison.md
similarity index 100%
rename from packages/docs/es/guide/comparison.md
rename to packages/docs/es/overview/comparison.md
diff --git a/packages/docs/es/guide/features.md b/packages/docs/es/overview/features.md
similarity index 100%
rename from packages/docs/es/guide/features.md
rename to packages/docs/es/overview/features.md
diff --git a/packages/docs/es/programmable/index.md b/packages/docs/es/programmable/index.md
index 9fa928c0d..fffdbd363 100644
--- a/packages/docs/es/programmable/index.md
+++ b/packages/docs/es/programmable/index.md
@@ -12,7 +12,7 @@ La interfaz del editor y las interfaces de automatización usan el mismo motor.
## Chat con IA
-El asistente integrado tiene acceso a 87 herramientas que cubren toda la superficie del editor. Describe lo que quieres en lenguaje natural — "añade una sombra de 16px a todos los botones", "crea un componente de tarjeta con variante para modo oscuro", "exporta cada frame de esta página a 2×".
+El asistente integrado tiene acceso a más de 90 herramientas que cubren toda la superficie del editor. Describe lo que quieres en lenguaje natural — "añade una sombra de 16px a todos los botones", "crea un componente de tarjeta con variante para modo oscuro", "exporta cada frame de esta página a 2×".
[Chat con IA →](./ai-chat)
diff --git a/packages/docs/es/guide/figma-comparison.md b/packages/docs/es/reference/figma-compatibility.md
similarity index 99%
rename from packages/docs/es/guide/figma-comparison.md
rename to packages/docs/es/reference/figma-compatibility.md
index 264ea1e9f..c8ea8ebf9 100644
--- a/packages/docs/es/guide/figma-comparison.md
+++ b/packages/docs/es/reference/figma-compatibility.md
@@ -215,7 +215,7 @@ Comparación característica por característica de las capacidades de Figma Des
| Code Connect | 🔲 | Vincular componentes de diseño a código |
| Fragmentos de código | 🟡 | Export JSX con resaltado y copia; sin fragmentos CSS/Swift/Kotlin |
| Figma for VS Code | 🔲 | Integración con plugin de editor |
-| Servidor MCP | ✅ | @open-pencil/mcp con transportes stdio + HTTP; 87 herramientas core + 3 de gestión de archivos = 90+ total |
+| Server MCP | ✅ | @open-pencil/mcp con transportes stdio + HTTP y más de 90 herramientas, incluidas operaciones de archivos |
| Herramientas CLI | ✅ | CLI headless: info, tree, find, export, analyze, node, pages, variables, eval; servidor MCP |
## Figma Draw
diff --git a/packages/docs/fr/development/contributing.md b/packages/docs/fr/development/contributing.md
deleted file mode 100644
index ace9b6ace..000000000
--- a/packages/docs/fr/development/contributing.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# Contribuer
-
-## Structure du projet
-
-```
-packages/
- core/ @open-pencil/core — moteur (zéro dépendance DOM)
- src/ Graphe de scène, renderer, layout, codec, kiwi, types
- cli/ @open-pencil/cli — CLI headless pour opérations .fig
- src/commands/ info, tree, find, export, eval, analyze
- mcp/ @open-pencil/mcp — serveur MCP pour outils IA
- src/ Transports stdio + HTTP (Hono), 87 outils
-src/
- components/ Vue SFCs (canevas, panneaux, barre d'outils, sélecteur de couleur)
- properties/ Sections du panneau de propriétés (Apparence, Remplissage, Contour, etc.)
- composables/ Entrée canevas, raccourcis clavier, hooks de rendu
- stores/ État de l'éditeur (réactivité Vue)
- engine/ Shims de ré-exportation depuis @open-pencil/core
- kiwi/ Shims de ré-exportation depuis @open-pencil/core
- types.ts Types partagés (ré-exportés depuis core)
- constants.ts Couleurs UI, défauts, seuils
-desktop/ Tauri v2 (Rust + config)
-tests/
- e2e/ Régression visuelle Playwright
- engine/ Tests unitaires (bun:test)
-docs/ Site de documentation VitePress
- specs/ Spécifications de capacités (source de vérité)
- changes/ Changements actifs et archivés
-```
-
-## Configuration du développement
-
-```sh
-bun install
-bun run dev # Éditeur sur localhost:1420
-bun run docs:dev # Docs sur localhost:5173
-```
-
-## Style de code
-
-### Outils
-
-| Outil | Commande | Objectif |
-|-------|----------|----------|
-| oxlint | `bun run lint` | Linting (basé sur Rust, rapide) |
-| oxfmt | `bun run format` | Formatage du code |
-| tsgo | `bun run typecheck` | Vérification de types (checker TypeScript basé sur Go) |
-
-Exécuter toutes les vérifications :
-
-```sh
-bun run check
-```
-
-### Conventions
-
-- **Noms de fichiers** — kebab-case (`scene-graph.ts`, `use-canvas-input.ts`)
-- **Composants** — PascalCase Vue SFCs (`EditorCanvas.vue`, `NumberField.vue`)
-- **Constantes** — SCREAMING_SNAKE_CASE
-- **Fonctions/variables** — camelCase
-- **Types/interfaces** — PascalCase
-
-### Conventions pour agents IA
-
-Les développeurs et agents IA doivent lire `AGENTS.md` à la racine du repo ([voir sur GitHub](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)). Couvre le rendu, le graphe de scène, les composants et instances, le layout, l'UI, le format de fichier, les conventions Tauri et les problèmes connus.
-
-## Apporter des changements
-
-3. Implémenter le changement
-4. Exécuter `bun run check` et `bun run test`
-5. Soumettre une pull request
-
-## Fichiers clés
-
-Le code source du moteur core se trouve dans `packages/core/src/`. Le code propre à l'app pour l'éditeur, les documents, l'IA, la collaboration, le shell, les démos et l'automatisation vit sous `src/app/*`; le SDK Vue contient le code canvas et composable réutilisable dans `packages/vue/src/`.
-
-| Fichier | Objectif |
-|---------|----------|
-| `packages/scene-graph/src/` | Graphe de scène : nœuds, variables, instances, hit testing et annulation |
-| `packages/core/src/canvas/renderer.ts` | Pipeline de rendu CanvasKit |
-| `packages/core/src/layout/` | Adaptateur layout Yoga |
-| `packages/core/src/clipboard.ts` | Presse-papiers compatible Figma |
-| `packages/core/src/vector/` | Modèle de réseau vectoriel |
-| `packages/core/src/io/formats/raster/render.ts` | Export d'image hors-écran (PNG/JPG/WEBP) |
-| `packages/kiwi/src/schema-runtime/` | Runtime de schéma et codec binaire Kiwi |
-| `packages/fig/src/node-change/` | Conversion entre SceneGraph et Figma NodeChange |
-| `packages/core/src/io/formats/fig/` | Orchestration de lecture/écriture .fig pour l'application |
-| `packages/cli/src/index.ts` | Point d'entrée du CLI |
-| `packages/core/src/tools/` | Définitions d'outils unifiées (IA, MCP, CLI) |
-| `packages/core/src/figma-api/` | Implémentation de Figma Plugin API |
-| `packages/mcp/src/server.ts` | Factory du serveur MCP |
-| `packages/cli/src/commands/` | Commandes CLI (info, tree, find, export, eval, analyze) |
-| `src/app/editor/session/create.ts` | Editor session assembly |
-| `packages/vue/src/canvas/CanvasRoot.vue` | Composable de rendu du canevas |
-| `packages/vue/src/canvas/useCanvasInput.ts` | Gestion des entrées souris/touch |
-| `src/app/shell/keyboard/use.ts` | Gestion des raccourcis clavier |
diff --git a/packages/docs/fr/development/testing.md b/packages/docs/fr/development/testing.md
deleted file mode 100644
index dfe989733..000000000
--- a/packages/docs/fr/development/testing.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# Tests
-
-## Vue d'ensemble
-
-| Type | Framework | Command | Location |
-|------|-----------|---------|----------|
-| E2E visual regression | Playwright | `bun run test` | `tests/e2e/` |
-| Figma CDP reference | Playwright | `bun run test:figma` | `tests/figma/` |
-| Unit tests | bun:test | `bun run test:unit` | `tests/engine/` |
-
-## Régression visuelle E2E
-
-```sh
-bun run test # Compare against baselines
-bun run test:update # Regenerate baselines
-```
-
-1. Playwright → headless browser
-2. `data-ready` HTML attribute
-3. Create shapes → screenshot → `toMatchSnapshot`
-
-## Tests de référence Figma CDP
-
-```sh
-bun run figma:debug # Launch Figma with debugging port
-bun run test:figma # Connect via CDP
-```
-
-## Tests unitaires
-
-```sh
-bun run test:unit
-```
-
-- Scene graph CRUD, hit testing
-- Fig-import pipeline
-- Layout computation (Yoga)
-- MCP server edge cases
-
-## Couverture des tests E2E
-
-| Test file | Scope |
-|-----------|-------|
-| `tests/e2e/layers-panel.spec.ts` | Layers panel |
-| `tests/e2e/visual.spec.ts` | Visual regression |
-
-## Objectifs de performance
-
-| Metric | Target |
-|--------|--------|
-| E2E suite | < 3s |
-| Unit tests | < 50ms |
diff --git a/packages/docs/fr/guide/getting-started.md b/packages/docs/fr/getting-started.md
similarity index 91%
rename from packages/docs/fr/guide/getting-started.md
rename to packages/docs/fr/getting-started.md
index b7a89693b..a550ce880 100644
--- a/packages/docs/fr/guide/getting-started.md
+++ b/packages/docs/fr/getting-started.md
@@ -39,4 +39,4 @@ Ouvre l'éditeur sur `http://localhost:1420`.
## Application de bureau (Tauri)
-Voir la [version anglaise](/guide/getting-started) pour les instructions détaillées par plateforme.
+Voir la [version anglaise](/getting-started) pour les instructions détaillées par plateforme.
diff --git a/packages/docs/fr/guide/architecture.md b/packages/docs/fr/guide/architecture.md
deleted file mode 100644
index a60796820..000000000
--- a/packages/docs/fr/guide/architecture.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# Architecture
-
-## Vue d'ensemble du système
-
-`mermaid
-graph TB
- subgraph Tauri["Tauri v2 Shell"]
- subgraph Editor["Editor (Web)"]
- UI["Vue 3 UI<br/>Toolbar · Panels · Properties<br/>Layers · Color Picker"]
- Skia["Skia CanvasKit (WASM, 7MB)<br/>Vector rendering · Text shaping<br/>Effects · Export"]
- subgraph Core["Core Engine (TS)"]
- SG[SceneGraph] --- Layout[Layout - Yoga]
- SG --- Selection
- Undo[Undo/Redo] --- Constraints
- Constraints --- HitTest[Hit Testing]
- end
- subgraph FileFormat["File Format Layer"]
- FigIO[".fig import/export"] --- Kiwi[Kiwi codec]
- Kiwi --- SVG[SVG export]
- end
- end
- MCP["MCP Server (90 tools, stdio+HTTP)"]
- Collab["P2P Collab (Trystero + Yjs)"]
- end
-`
-
-## Disposition de l'éditeur
-
-L'interface suit le layout UI3 de Figma — barre d'outils en bas, navigation à gauche, propriétés à droite :
-
-- **Panneau de navigation (gauche)** — Arbre des calques, panneau des pages
-- **Canvas (centre)** — Canvas infini avec rendu CanvasKit, zoom/pan
-- **Panneau de propriétés (droite)** — Sections contextuelles : Apparence, Remplissage, Contour, Typographie, Layout, Position
-- **Barre d'outils (bas)** — Sélection d'outil : Sélectionner, Frame, Section, Rectangle, Ellipse, Ligne, Texte, Plume, Main
-
-## Composants
-
-### Rendu (CanvasKit WASM)
-
-Le même moteur de rendu que Figma. CanvasKit fournit un dessin 2D accéléré par GPU avec formes vectorielles, mise en forme du texte via Paragraph API, effets (ombres, flous, modes de fusion) et export (PNG, SVG). Le binaire WASM de 7 Mo se charge au démarrage et crée une surface GPU sur le canvas HTML.
-
-Le renderer est découpé en modules spécialisés dans `packages/core/src/renderer/` : parcours de scène, overlays, remplissages, contours, formes, effets, règles, étiquettes et curseurs distants.
-
-### Graphe de scène
-
-`Map<string, Node>` plat indexé par des chaînes GUID. Structure en arbre via des références `parentIndex`. Fournit une recherche O(1), un parcours efficace, du hit testing et des requêtes par zone rectangulaire pour la sélection par marquise.
-
-Le graphe émet des événements typés via nanoevents : `node:created`, `node:updated`, `node:deleted`, `node:reparented`, `node:reordered`. Les sous-systèmes s'y abonnent au lieu d'un câblage manuel — l'éditeur les utilise pour l'invalidation du rendu et la synchronisation d'instances de composants batchée par microtâche, le système de collaboration pour la propagation Yjs.
-
-Voir la [Référence du graphe de scène](/reference/scene-graph) pour les détails internes.
-
-### Moteur de layout (Yoga WASM)
-
-Yoga de Meta fournit le calcul de layout CSS flexbox et grid via un [fork](https://github.com/open-pencil/yoga/tree/grid) avec support CSS Grid. Un adaptateur fin mappe les noms de propriétés Figma vers les équivalents Yoga :
-
-| Propriété Figma | Équivalent Yoga |
-|---|---|
-| `stackMode: HORIZONTAL` | `flexDirection: row` |
-| `stackMode: VERTICAL` | `flexDirection: column` |
-| `stackSpacing` | `gap` |
-| `stackPadding` | `padding` |
-| `stackJustify` | `justifyContent` |
-| `stackChildPrimaryGrow` | `flexGrow` |
-
-### Format de fichier (Kiwi binaire)
-
-Réutilise le codec binaire Kiwi de Figma avec 194 définitions de message/enum/struct. Import : analyser l'en-tête → décompresser Zstd → décoder Kiwi → `NodeChange`[] → graphe de scène. L'export inverse le processus avec génération de miniature.
-
-Voir la [Référence du format de fichier](/reference/file-format) pour plus de détails.
-
-### IA et outils
-
-Les outils sont définis une seule fois dans `packages/core/src/tools/`, découpés par domaine : read, create, modify, structure, variables, vector, analyze. Chaque outil a des paramètres typés et une fonction `execute(figma, args)`. Les adaptateurs les convertissent pour :
-
-- **Chat IA** — schémas valibot, multi-fournisseur (Anthropic, OpenAI, Google AI, OpenRouter, endpoints compatibles)
-- **Serveur MCP** — schémas zod, transports stdio + HTTP
-- **CLI** — accessible via la commande `eval`
-
-90+ outils core + 3 outils de gestion de fichiers MCP. Inclut requête XPath (`query_nodes`), inspection JSX (`get_jsx`, `diff_jsx`), description sémantique (`describe`) et vérification visuelle (`export_image` renvoie des images au modèle).
-
-### Annuler/Rétablir
-
-Patron de commande inverse. Avant d'appliquer tout changement, les champs concernés sont capturés en snapshot. Le snapshot devient l'opération inverse. Le batching regroupe les changements rapides (comme le glissement) en entrées d'annulation uniques.
-
-### Presse-papiers
-
-Presse-papiers bidirectionnel compatible Figma. Encode/décode le binaire Kiwi (même format que les fichiers .fig) via les événements natifs copier/coller du navigateur. Gère le redimensionnement des chemins vectoriels, les enfants d'instances, la détection des ensembles de composants et l'application des surcharges.
-
-### Collaboration P2P
-
-Collaboration peer-to-peer en temps réel via Trystero (WebRTC) + Yjs CRDT. Sans serveur relais — signalisation via des brokers MQTT publics, STUN/TURN pour le traversal NAT. Le protocole d'awareness fournit des curseurs en direct, des sélections et de la présence. Persistance locale via y-indexeddb.
-
-### Pont RPC CLI-vers-application
-
-Lorsque l'application de bureau est lancée, les commandes CLI s'y connectent via WebSocket au lieu de nécessiter un fichier .fig. Le serveur d'automatisation tourne sur `127.0.0.1:7600` (HTTP) et `127.0.0.1:7601` (WebSocket). Les commandes s'exécutent sur l'état en direct de l'éditeur, permettant aux scripts d'automatisation et aux agents IA d'interagir avec l'application en cours d'exécution.
-
-## Prochaines étapes
-
-### Ensemble complet d'outils figma-use
-
-Le serveur MCP expose actuellement 90 outils. L'implémentation de référence dans [figma-use](https://github.com/dannote/figma-use) en compte 118. Les outils restants couvrent les contraintes de layout avancées, les connexions de prototype, l'édition avancée des propriétés de composants et les opérations en masse sur les documents.
-
-### Outillage de design pour la CI
-
-Le CLI headless supporte déjà `analyze colors/typography/spacing/clusters`. Prochaine étape : intégration GitHub Actions pour le linting de design automatisé et la régression visuelle dans les PRs.
-
-### Prototypage
-
-Transitions frame-à-frame, déclencheurs d'interaction (clic, survol, glissement), gestion des overlays et mode aperçu plein écran.
-
-### Signature de code Windows
-
-Les binaires macOS sont signés et notarisés depuis la v0.6.0. La signature Authenticode Windows via Azure Code Signing est prévue pour supprimer l'avertissement SmartScreen.
diff --git a/packages/docs/fr/guide/tech-stack.md b/packages/docs/fr/guide/tech-stack.md
deleted file mode 100644
index 5e503fac4..000000000
--- a/packages/docs/fr/guide/tech-stack.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# Stack technique
-
-## Technologies principales
-
-| Couche | Technologie | Pourquoi |
-|--------|-----------|----------|
-| **Rendu** | Skia CanvasKit WASM | Même moteur que Figma — performances éprouvées, accéléré GPU, pixel-parfait |
-| **Framework UI** | Vue 3 + VueUse | API de composition réactive, excellent support TypeScript |
-| **Composants** | Reka UI | Primitives UI headless et accessibles (tree, slider, etc.) |
-| **Stylisation** | Tailwind CSS 4 | Utility-first, itération rapide, thème sombre |
-| **Layout** | Yoga WASM | Moteur CSS flexbox de Meta, éprouvé dans React Native |
-| **Format de fichier** | Kiwi binaire + Zstd | Format propre de Figma — compact, parsing rapide, compatible .fig |
-| **Collaboration** | Trystero + Yjs | P2P WebRTC via signalisation MQTT, sync CRDT, persistance y-indexeddb |
-| **Couleur** | culori | Conversions d'espaces colorimétriques (HSV, RGB, hex) |
-| **IA/MCP** | MCP SDK + Hono | 90+ outils pour le codage IA, transports stdio + HTTP |
-| **Transform JSX** | Sucrase | 201 Ko JSX → JS, synchrone, compatible navigateur |
-| **Événements** | nanoevents | 108 octets, émetteur typé pour les mutations du SceneGraph |
-| **Transform JSX** | Sucrase | 201 Ko JSX → JS, synchrone, compatible navigateur |
-| **Événements** | nanoevents | 108 octets, émetteur typé pour les mutations du SceneGraph |
-| **Desktop** | Tauri v2 | ~5 Mo app native (vs ~100 Mo d'Electron), backend Rust |
-| **Build** | Vite 7 | HMR rapide, modules ES natifs |
-| **Test** | Playwright + bun:test | Régression visuelle (E2E) + tests unitaires rapides |
-| **Linting** | oxlint | Basé sur Rust, ordres de grandeur plus rapide qu'ESLint |
-| **Formatage** | oxfmt | Formateur basé sur Rust |
-| **Vérification de types** | typescript-go (tsgo) | Implémentation native en Go du vérificateur de types TypeScript |
-
-## Dépendances principales
-
-```json
-{
- "canvaskit-wasm": "^0.40.0",
- "vue": "^3.5.29",
- "yoga-layout": "npm:@open-pencil/[email protected]",
- "nanoevents": "^9.1.0",
- "sucrase": "^3.35.1",
- "reka-ui": "^2.8.2",
- "tailwindcss": "^4.2.1",
- "culori": "^4.0.2",
- "fzstd": "^0.1.1",
- "fflate": "^0.8.2",
- "trystero": "^0.20.0",
- "yjs": "^13.6.24",
- "y-indexeddb": "^9.0.12"
-}
-```
-
-## Pourquoi pas...
-
-### Pourquoi pas le rendu SVG ?
-
-SVG est lent pour les documents complexes. Chaque nœud est un élément DOM — 10 000 nœuds signifient 10 000 éléments DOM avec overhead de layout, peinture et composition. CanvasKit dessine tout sur une seule surface GPU.
-
-### Pourquoi pas Electron (comme Figma desktop) ?
-
-Tauri v2 utilise le webview système (~5 Mo) au lieu d'embarquer Chromium (~100 Mo). Le backend Rust fournit des performances natives pour les E/S fichier et l'intégration système.
-
-### Pourquoi pas React ?
-
-Le projet a migré de React vers Vue 3 très tôt. Le système de réactivité de Vue et les composables VueUse se sont avérés plus ergonomiques.
-
-### Pourquoi pas un moteur de layout personnalisé ?
-
-Yoga est maintenu par Meta, éprouvé sur des milliards d'appareils React Native et implémente la spécification CSS flexbox.
-
-## Technologies supplémentaires
-
-| Technologie | Objectif | Statut |
-|-----------|---------|--------|
-| CSS Grid dans Yoga | Auto layout basé sur une grille | Livré via [fork Yoga](https://github.com/open-pencil/yoga/tree/grid) (`@open-pencil/yoga-layout`) |
diff --git a/packages/docs/fr/guide/comparison.md b/packages/docs/fr/overview/comparison.md
similarity index 100%
rename from packages/docs/fr/guide/comparison.md
rename to packages/docs/fr/overview/comparison.md
diff --git a/packages/docs/fr/guide/features.md b/packages/docs/fr/overview/features.md
similarity index 100%
rename from packages/docs/fr/guide/features.md
rename to packages/docs/fr/overview/features.md
diff --git a/packages/docs/fr/programmable/index.md b/packages/docs/fr/programmable/index.md
index 337ac8731..499606247 100644
--- a/packages/docs/fr/programmable/index.md
+++ b/packages/docs/fr/programmable/index.md
@@ -12,7 +12,7 @@ L'interface de l'éditeur et les interfaces d'automatisation utilisent le même
## Chat IA
-L'assistant intégré a accès à 87 outils qui couvrent l'ensemble des fonctionnalités de l'éditeur. Décrivez ce que vous voulez en langage naturel — « ajouter une ombre portée de 16px à tous les boutons », « créer un composant carte avec une variante mode sombre », « exporter chaque frame de cette page en 2× ».
+L'assistant intégré a accès à plus de 90 outils qui couvrent l'ensemble des fonctionnalités de l'éditeur. Décrivez ce que vous voulez en langage naturel — « ajouter une ombre portée de 16px à tous les boutons », « créer un composant carte avec une variante mode sombre », « exporter chaque frame de cette page en 2× ».
[Chat IA →](./ai-chat)
diff --git a/packages/docs/fr/guide/figma-comparison.md b/packages/docs/fr/reference/figma-compatibility.md
similarity index 100%
rename from packages/docs/fr/guide/figma-comparison.md
rename to packages/docs/fr/reference/figma-compatibility.md
diff --git a/packages/docs/guide/getting-started.md b/packages/docs/getting-started.md
similarity index 94%
rename from packages/docs/guide/getting-started.md
rename to packages/docs/getting-started.md
index dbee507ad..3f81f61f3 100644
--- a/packages/docs/guide/getting-started.md
+++ b/packages/docs/getting-started.md
@@ -61,7 +61,8 @@ Opens the editor at `http://localhost:1420`.
| `bun run test:update` | Regenerate screenshot baselines |
| `bun run test:unit` | Unit tests (bun:test) |
| `bun run docs:dev` | Documentation dev server |
-| `bun run docs:build` | Build documentation site |
+| `bun run docs:build` | Build documentation locally (fast validation build) |
+| `bun run docs:build:production` | Build deployable documentation, including LLM files |
## Desktop App (Tauri)
diff --git a/packages/docs/it/development/contributing.md b/packages/docs/it/development/contributing.md
deleted file mode 100644
index 78c5205ab..000000000
--- a/packages/docs/it/development/contributing.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# Contribuire
-
-## Struttura del progetto
-
-```
-packages/
- core/ @open-pencil/core — motore (zero dipendenze DOM)
- src/ Grafo scena, renderer, layout, codec, kiwi, tipi
- cli/ @open-pencil/cli — CLI headless per operazioni .fig
- src/commands/ info, tree, find, export, eval, analyze
- mcp/ @open-pencil/mcp — server MCP per strumenti IA
- src/ Trasporti stdio + HTTP (Hono), 87 strumenti
-src/
- components/ Vue SFCs (canvas, pannelli, barra strumenti, selettore colore)
- properties/ Sezioni pannello proprietà (Aspetto, Riempimento, Contorno, ecc.)
- composables/ Input canvas, scorciatoie tastiera, hook di rendering
- stores/ Stato editor (reattività Vue)
- engine/ Shim di ri-esportazione da @open-pencil/core
- kiwi/ Shim di ri-esportazione da @open-pencil/core
- types.ts Tipi condivisi (ri-esportati da core)
- constants.ts Colori UI, default, soglie
-desktop/ Tauri v2 (Rust + config)
-tests/
- e2e/ Regressione visiva Playwright
- engine/ Test unitari (bun:test)
-docs/ Sito documentazione VitePress
- specs/ Specifiche di capacità (fonte di verità)
- changes/ Cambiamenti attivi e archiviati
-```
-
-## Configurazione sviluppo
-
-```sh
-bun install
-bun run dev # Editor su localhost:1420
-bun run docs:dev # Docs su localhost:5173
-```
-
-## Stile di codice
-
-### Strumenti
-
-| Strumento | Comando | Scopo |
-|-----------|---------|-------|
-| oxlint | `bun run lint` | Linting (basato su Rust, veloce) |
-| oxfmt | `bun run format` | Formattazione codice |
-| tsgo | `bun run typecheck` | Verifica tipi (checker TypeScript basato su Go) |
-
-Eseguire tutte le verifiche:
-
-```sh
-bun run check
-```
-
-### Convenzioni
-
-- **Nomi file** — kebab-case (`scene-graph.ts`, `use-canvas-input.ts`)
-- **Componenti** — PascalCase Vue SFCs (`EditorCanvas.vue`, `NumberField.vue`)
-- **Costanti** — SCREAMING_SNAKE_CASE
-- **Funzioni/variabili** — camelCase
-- **Tipi/interfacce** — PascalCase
-
-### Convenzioni per agenti IA
-
-Sviluppatori e agenti IA dovrebbero leggere `AGENTS.md` nella root del repo ([vedi su GitHub](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)). Copre rendering, grafo scena, componenti e istanze, layout, UI, formato file, convenzioni Tauri e problemi noti.
-
-## Apportare modifiche
-
-3. Implementare il cambiamento
-4. Eseguire `bun run check` e `bun run test`
-5. Inviare una pull request
-
-## File chiave
-
-Il codice sorgente del motore core si trova in `packages/core/src/`. Il codice specifico dell'app per editor, documenti, IA, collaborazione, shell, demo e automazione vive in `src/app/*`; l'SDK Vue contiene il codice canvas e composable riutilizzabile in `packages/vue/src/`.
-
-| File | Scopo |
-|------|-------|
-| `packages/scene-graph/src/` | Grafo scena: nodi, variabili, istanze, hit testing e annullamento |
-| `packages/core/src/canvas/renderer.ts` | Pipeline di rendering CanvasKit |
-| `packages/core/src/layout/` | Adattatore layout Yoga |
-| `packages/core/src/clipboard.ts` | Appunti compatibili con Figma |
-| `packages/core/src/vector/` | Modello rete vettoriale |
-| `packages/core/src/io/formats/raster/render.ts` | Export immagine offscreen (PNG/JPG/WEBP) |
-| `packages/kiwi/src/schema-runtime/` | Runtime dello schema e codec binario Kiwi |
-| `packages/fig/src/node-change/` | Conversione tra SceneGraph e Figma NodeChange |
-| `packages/core/src/io/formats/fig/` | Orchestrazione lettura/scrittura .fig per l'app |
-| `packages/cli/src/index.ts` | Punto di ingresso CLI |
-| `packages/core/src/tools/` | Definizioni strumenti unificate (IA, MCP, CLI) |
-| `packages/core/src/figma-api/` | Implementazione Figma Plugin API |
-| `packages/mcp/src/server.ts` | Factory del server MCP |
-| `packages/cli/src/commands/` | Comandi CLI (info, tree, find, export, eval, analyze) |
-| `src/app/editor/session/create.ts` | Editor session assembly |
-| `packages/vue/src/canvas/CanvasRoot.vue` | Composable rendering canvas |
-| `packages/vue/src/canvas/useCanvasInput.ts` | Gestione input mouse/touch |
-| `src/app/shell/keyboard/use.ts` | Gestione scorciatoie tastiera |
diff --git a/packages/docs/it/development/testing.md b/packages/docs/it/development/testing.md
deleted file mode 100644
index 5d1be2b1d..000000000
--- a/packages/docs/it/development/testing.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# Testing
-
-## Panoramica
-
-| Type | Framework | Command | Location |
-|------|-----------|---------|----------|
-| E2E visual regression | Playwright | `bun run test` | `tests/e2e/` |
-| Figma CDP reference | Playwright | `bun run test:figma` | `tests/figma/` |
-| Unit tests | bun:test | `bun run test:unit` | `tests/engine/` |
-
-## Regressione visuale E2E
-
-```sh
-bun run test # Compare against baselines
-bun run test:update # Regenerate baselines
-```
-
-1. Playwright → headless browser
-2. `data-ready` HTML attribute
-3. Create shapes → screenshot → `toMatchSnapshot`
-
-## Test di riferimento Figma CDP
-
-```sh
-bun run figma:debug # Launch Figma with debugging port
-bun run test:figma # Connect via CDP
-```
-
-## Test unitari
-
-```sh
-bun run test:unit
-```
-
-- Scene graph CRUD, hit testing
-- Fig-import pipeline
-- Layout computation (Yoga)
-- MCP server edge cases
-
-## Copertura test E2E
-
-| Test file | Scope |
-|-----------|-------|
-| `tests/e2e/layers-panel.spec.ts` | Layers panel |
-| `tests/e2e/visual.spec.ts` | Visual regression |
-
-## Obiettivi di prestazione
-
-| Metric | Target |
-|--------|--------|
-| E2E suite | < 3s |
-| Unit tests | < 50ms |
diff --git a/packages/docs/it/guide/getting-started.md b/packages/docs/it/getting-started.md
similarity index 84%
rename from packages/docs/it/guide/getting-started.md
rename to packages/docs/it/getting-started.md
index 81ff82549..43758678a 100644
--- a/packages/docs/it/guide/getting-started.md
+++ b/packages/docs/it/getting-started.md
@@ -49,11 +49,12 @@ Apre l'editor su `http://localhost:1420`.
| `bun run test` | E2E regressione visuale (Playwright) |
| `bun run test:unit` | Test unitari (bun:test) |
| `bun run docs:dev` | Server documentazione |
-| `bun run docs:build` | Build sito documentazione |
+| `bun run docs:build` | Build locale rapido della documentazione |
+| `bun run docs:build:production` | Build completo e distribuibile della documentazione |
## App desktop (Tauri)
-L'app desktop richiede Rust e prerequisiti specifici per la piattaforma. Consultare la [versione inglese](/guide/getting-started) per le istruzioni dettagliate per macOS, Windows e Linux.
+L'app desktop richiede Rust e prerequisiti specifici per la piattaforma. Consultare la [versione inglese](/getting-started) per le istruzioni dettagliate per macOS, Windows e Linux.
```sh
bun run tauri dev
diff --git a/packages/docs/it/guide/architecture.md b/packages/docs/it/guide/architecture.md
deleted file mode 100644
index 152cbd38c..000000000
--- a/packages/docs/it/guide/architecture.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# Architettura
-
-## Panoramica del Sistema
-
-`mermaid
-graph TB
- subgraph Tauri["Tauri v2 Shell"]
- subgraph Editor["Editor (Web)"]
- UI["Vue 3 UI<br/>Toolbar · Panels · Properties<br/>Layers · Color Picker"]
- Skia["Skia CanvasKit (WASM, 7MB)<br/>Vector rendering · Text shaping<br/>Effects · Export"]
- subgraph Core["Core Engine (TS)"]
- SG[SceneGraph] --- Layout[Layout - Yoga]
- SG --- Selection
- Undo[Undo/Redo] --- Constraints
- Constraints --- HitTest[Hit Testing]
- end
- subgraph FileFormat["File Format Layer"]
- FigIO[".fig import/export"] --- Kiwi[Kiwi codec]
- Kiwi --- SVG[SVG export]
- end
- end
- MCP["MCP Server (90 tools, stdio+HTTP)"]
- Collab["P2P Collab (Trystero + Yjs)"]
- end
-`
-
-## Layout dell'Editor
-
-L'interfaccia segue il layout UI3 di Figma — barra degli strumenti in basso, navigazione a sinistra, proprietà a destra:
-
-- **Pannello navigazione (sinistra)** — Albero dei livelli, pannello pagine
-- **Canvas (centro)** — Canvas infinito con rendering CanvasKit, zoom/pan
-- **Pannello proprietà (destra)** — Sezioni sensibili al contesto: Aspetto, Riempimento, Bordo, Tipografia, Layout, Posizione
-- **Barra degli strumenti (basso)** — Selezione strumenti: Seleziona, Frame, Sezione, Rettangolo, Ellisse, Linea, Testo, Penna, Mano
-
-## Componenti
-
-### Rendering (CanvasKit WASM)
-
-Lo stesso motore di rendering di Figma. CanvasKit fornisce disegno 2D accelerato dalla GPU con forme vettoriali, formattazione del testo tramite Paragraph API, effetti (ombre, sfocature, modalità di fusione) ed esportazione (PNG, SVG). Il binario WASM da 7MB viene caricato all'avvio e crea una superficie GPU sul canvas HTML.
-
-Il renderer è suddiviso in moduli specializzati in `packages/core/src/renderer/`: attraversamento della scena, overlay, riempimenti, bordi, forme, effetti, righelli, etichette e cursori remoti.
-
-### Scene Graph
-
-`Map<string, Node>` piatto indicizzato da stringhe GUID. Struttura ad albero tramite riferimenti `parentIndex`. Fornisce lookup O(1), attraversamento efficiente, hit testing e query per area rettangolare per la selezione con marquee.
-
-Il grafo emette eventi tipizzati tramite nanoevents: `node:created`, `node:updated`, `node:deleted`, `node:reparented`, `node:reordered`. I sottosistemi si iscrivono a questi eventi invece del cablaggio manuale — l'editor li usa per l'invalidazione del render e la sincronizzazione delle istanze dei componenti con microtask batching, il sistema di collaborazione per la propagazione Yjs.
-
-Consulta il [riferimento Scene Graph](/it/reference/scene-graph) per i dettagli interni.
-
-### Motore di Layout (Yoga WASM)
-
-Yoga di Meta fornisce il calcolo del layout CSS flexbox e grid tramite un [fork](https://github.com/open-pencil/yoga/tree/grid) con supporto CSS Grid. Un adattatore sottile mappa i nomi delle proprietà Figma agli equivalenti Yoga:
-
-| Proprietà Figma | Equivalente Yoga |
-|---|---|
-| `stackMode: HORIZONTAL` | `flexDirection: row` |
-| `stackMode: VERTICAL` | `flexDirection: column` |
-| `stackSpacing` | `gap` |
-| `stackPadding` | `padding` |
-| `stackJustify` | `justifyContent` |
-| `stackChildPrimaryGrow` | `flexGrow` |
-
-### Formato File (Kiwi Binary)
-
-Riutilizza il codec binario Kiwi di Figma con 194 definizioni di messaggio/enum/struct. Importazione: analizza l'header → decompressione Zstd → decodifica Kiwi → `NodeChange`[] → scene graph. L'esportazione inverte il processo con generazione di miniature.
-
-Consulta il [riferimento Formato File](/it/reference/file-format) per i dettagli.
-
-### AI e Strumenti
-
-Gli strumenti sono definiti una sola volta in `packages/core/src/tools/`, suddivisi per dominio: read, create, modify, structure, variables, vector, analyze. Ogni strumento ha parametri tipizzati e una funzione `execute(figma, args)`. Gli adattatori li convertono per:
-
-- **Chat AI** — schema valibot, multi-provider (Anthropic, OpenAI, Google AI, OpenRouter, endpoint compatibili)
-- **Server MCP** — schema zod, trasporti stdio + HTTP
-- **CLI** — disponibili tramite il comando `eval`
-
-90+ strumenti core + 3 strumenti di gestione file MCP. Include query XPath (`query_nodes`), ispezione JSX (`get_jsx`, `diff_jsx`), descrizione semantica (`describe`) e verifica visiva (`export_image` restituisce immagini al modello).
-
-### Annulla/Ripristina
-
-Pattern a comandi inversi. Prima di applicare qualsiasi modifica, i campi interessati vengono salvati in uno snapshot. Lo snapshot diventa l'operazione inversa. Il batching raggruppa le modifiche rapide (come il trascinamento) in singole voci di annullamento.
-
-### Appunti
-
-Appunti bidirezionali compatibili con Figma. Codifica/decodifica binario Kiwi (stesso formato dei file .fig) tramite eventi nativi di copia/incolla del browser. Gestisce il ridimensionamento dei tracciati vettoriali, i figli delle istanze, il rilevamento dei set di componenti e l'applicazione degli override.
-
-### Collaborazione P2P
-
-Collaborazione peer-to-peer in tempo reale tramite Trystero (WebRTC) + Yjs CRDT. Nessun relay server — segnalazione tramite broker MQTT pubblici, STUN/TURN per l'attraversamento NAT. Il protocollo Awareness fornisce cursori live, selezioni e presenza. Persistenza locale tramite y-indexeddb.
-
-### Bridge RPC CLI-App
-
-Quando l'app desktop è in esecuzione, i comandi CLI si connettono tramite WebSocket invece di richiedere un file .fig. Il server di automazione è in esecuzione su `127.0.0.1:7600` (HTTP) e `127.0.0.1:7601` (WebSocket). I comandi vengono eseguiti sullo stato dell'editor live, consentendo a script di automazione e agenti AI di interagire con l'app in esecuzione.
-
-## Prossimi Passi
-
-### Set Completo di Strumenti figma-use
-
-Il server MCP attualmente espone 90 strumenti. L'implementazione di riferimento in [figma-use](https://github.com/dannote/figma-use) ne ha 118. Gli strumenti rimanenti coprono vincoli di layout avanzati, connessioni per prototipi, modifica avanzata delle proprietà dei componenti e operazioni in blocco sui documenti.
-
-### Strumenti di Design per CI
-
-La CLI headless supporta già `analyze colors/typography/spacing/clusters`. Prossimamente: integrazione con GitHub Actions per linting automatico del design e regressione visiva nelle PR.
-
-### Prototipazione
-
-Transizioni frame-to-frame, trigger di interazione (clic, hover, trascinamento), gestione degli overlay e modalità anteprima a schermo intero.
-
-### Firma del Codice per Windows
-
-I binari macOS sono firmati e autenticati dalla v0.6.0. La firma Windows Authenticode tramite Azure Code Signing è pianificata per rimuovere l'avviso SmartScreen.
diff --git a/packages/docs/it/guide/tech-stack.md b/packages/docs/it/guide/tech-stack.md
deleted file mode 100644
index e8e7e4847..000000000
--- a/packages/docs/it/guide/tech-stack.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# Stack tecnologico
-
-## Tecnologie principali
-
-| Livello | Tecnologia | Perché |
-|---------|-----------|--------|
-| **Rendering** | Skia CanvasKit WASM | Stesso motore di Figma — prestazioni provate, accelerato GPU, pixel-perfetto |
-| **Framework UI** | Vue 3 + VueUse | API di composizione reattiva, eccellente supporto TypeScript |
-| **Componenti** | Reka UI | Primitivi UI headless e accessibili (tree, slider, ecc.) |
-| **Stile** | Tailwind CSS 4 | Utility-first, iterazione rapida, tema scuro |
-| **Layout** | Yoga WASM | Motore CSS flexbox di Meta, collaudato in React Native |
-| **Formato file** | Kiwi binario + Zstd | Formato proprio di Figma — compatto, parsing veloce, compatibile .fig |
-| **Collaborazione** | Trystero + Yjs | P2P WebRTC via segnalazione MQTT, sync CRDT, persistenza y-indexeddb |
-| **Colore** | culori | Conversioni spazio colore (HSV, RGB, hex) |
-| **IA/MCP** | MCP SDK + Hono | 90+ strumenti per il coding IA, trasporti stdio + HTTP |
-| **JSX Transform** | Sucrase | 201 KB JSX → JS, sincrono, compatibile browser |
-| **Eventi** | nanoevents | 108 byte, emettitore eventi tipizzato per mutazioni SceneGraph |
-| **JSX Transform** | Sucrase | 201 KB JSX → JS, sincrono, compatibile browser |
-| **Eventi** | nanoevents | 108 byte, emettitore eventi tipizzato per mutazioni SceneGraph |
-| **Desktop** | Tauri v2 | ~5 MB app nativa (vs ~100 MB di Electron), backend Rust |
-| **Build** | Vite 7 | HMR veloce, moduli ES nativi |
-| **Test** | Playwright + bun:test | Regressione visiva (E2E) + test unitari veloci |
-| **Linting** | oxlint | Basato su Rust, ordini di grandezza più veloce di ESLint |
-| **Formattazione** | oxfmt | Formattatore basato su Rust |
-| **Verifica tipi** | typescript-go (tsgo) | Implementazione nativa in Go del type checker TypeScript |
-
-## Dipendenze principali
-
-```json
-{
- "canvaskit-wasm": "^0.40.0",
- "vue": "^3.5.29",
- "yoga-layout": "npm:@open-pencil/[email protected]",
- "nanoevents": "^9.1.0",
- "sucrase": "^3.35.1",
- "reka-ui": "^2.8.2",
- "tailwindcss": "^4.2.1",
- "culori": "^4.0.2",
- "fzstd": "^0.1.1",
- "fflate": "^0.8.2",
- "trystero": "^0.20.0",
- "yjs": "^13.6.24",
- "y-indexeddb": "^9.0.12"
-}
-```
-
-## Perché non...
-
-### Perché non il rendering SVG?
-
-SVG è lento per documenti complessi. Ogni nodo è un elemento DOM — 10.000 nodi significano 10.000 elementi DOM con overhead di layout, disegno e composizione. CanvasKit disegna tutto su una singola superficie GPU.
-
-### Perché non Electron (come Figma desktop)?
-
-Tauri v2 usa il webview di sistema (~5 MB) invece di incorporare Chromium (~100 MB). Il backend Rust fornisce prestazioni native per I/O file e integrazione di sistema.
-
-### Perché non React?
-
-Il progetto è migrato da React a Vue 3 nelle fasi iniziali. Il sistema di reattività di Vue e i composables VueUse si sono rivelati più ergonomici.
-
-### Perché non un motore di layout personalizzato?
-
-Yoga è mantenuto da Meta, collaudato su miliardi di dispositivi React Native e implementa la specifica CSS flexbox.
-
-## Tecnologie pianificate
-
-| Tecnologia | Scopo | Fase |
-|-----------|---------|-------|
-| CSS Grid in Yoga | Auto layout basato su griglia | ✅ Incluso tramite [fork Yoga](https://github.com/open-pencil/yoga/tree/grid) (`@open-pencil/yoga-layout`) |
diff --git a/packages/docs/it/guide/comparison.md b/packages/docs/it/overview/comparison.md
similarity index 100%
rename from packages/docs/it/guide/comparison.md
rename to packages/docs/it/overview/comparison.md
diff --git a/packages/docs/it/guide/features.md b/packages/docs/it/overview/features.md
similarity index 100%
rename from packages/docs/it/guide/features.md
rename to packages/docs/it/overview/features.md
diff --git a/packages/docs/it/programmable/index.md b/packages/docs/it/programmable/index.md
index a8db4351e..e650cf098 100644
--- a/packages/docs/it/programmable/index.md
+++ b/packages/docs/it/programmable/index.md
@@ -12,7 +12,7 @@ L'interfaccia dell'editor e le interfacce di automazione utilizzano lo stesso mo
## Chat IA
-L'assistente integrato ha accesso a 87 strumenti che coprono l'intera superficie dell'editor. Descrivi ciò che vuoi in linguaggio naturale — "aggiungi un'ombra esterna di 16px a tutti i pulsanti", "crea un componente card con variante dark mode", "esporta ogni frame di questa pagina a 2×".
+L'assistente integrato ha accesso a oltre 90 strumenti che coprono l'intera superficie dell'editor. Descrivi ciò che vuoi in linguaggio naturale — "aggiungi un'ombra esterna di 16px a tutti i pulsanti", "crea un componente card con variante dark mode", "esporta ogni frame di questa pagina a 2×".
[Chat IA →](./ai-chat)
diff --git a/packages/docs/it/guide/figma-comparison.md b/packages/docs/it/reference/figma-compatibility.md
similarity index 99%
rename from packages/docs/it/guide/figma-comparison.md
rename to packages/docs/it/reference/figma-compatibility.md
index ff4cf9e42..081a5bf43 100644
--- a/packages/docs/it/guide/figma-comparison.md
+++ b/packages/docs/it/reference/figma-compatibility.md
@@ -215,7 +215,7 @@ Confronto funzionalità per funzionalità delle capacità di Figma Design con lo
| Code Connect | 🔲 | Collegare componenti design al codice |
| Frammenti di codice | 🟡 | Export JSX con evidenziazione e copia; nessun frammento CSS/Swift/Kotlin |
| Figma for VS Code | 🔲 | Integrazione plugin editor |
-| Server MCP | ✅ | @open-pencil/mcp con trasporti stdio + HTTP; 87 strumenti core + 3 gestione file = 90+ total |
+| Server MCP | ✅ | @open-pencil/mcp con trasporti stdio + HTTP e oltre 90 strumenti, incluse le operazioni sui file |
| Strumenti CLI | ✅ | CLI headless: info, tree, find, export, analyze, node, pages, variables, eval; server MCP |
## Figma Draw
diff --git a/packages/docs/guide/comparison.md b/packages/docs/overview/comparison.md
similarity index 100%
rename from packages/docs/guide/comparison.md
rename to packages/docs/overview/comparison.md
diff --git a/packages/docs/guide/features.md b/packages/docs/overview/features.md
similarity index 100%
rename from packages/docs/guide/features.md
rename to packages/docs/overview/features.md
diff --git a/packages/docs/package.json b/packages/docs/package.json
index 085947f6d..efbd76276 100644
--- a/packages/docs/package.json
+++ b/packages/docs/package.json
@@ -9,7 +9,9 @@
},
"scripts": {
"dev": "vitepress dev",
- "build": "NODE_OPTIONS=--max-old-space-size=8192 vitepress build",
+ "build": "OPENPENCIL_DOCS_FAST_BUILD=1 NODE_OPTIONS=--max-old-space-size=8192 vitepress build --minify=false --buildConcurrency=8",
+ "build:production": "NODE_OPTIONS=--max-old-space-size=8192 vitepress build --minify=esbuild --buildConcurrency=8",
+ "check": "bun ../../tools/docs/src/check.ts",
"preview": "vitepress preview"
},
"devDependencies": {
diff --git a/packages/docs/pl/development/contributing.md b/packages/docs/pl/development/contributing.md
deleted file mode 100644
index fe53aea51..000000000
--- a/packages/docs/pl/development/contributing.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# Współtworzenie
-
-## Struktura projektu
-
-```
-packages/
- core/ @open-pencil/core — silnik (zero zależności DOM)
- src/ Graf sceny, renderer, layout, kodek, kiwi, typy
- cli/ @open-pencil/cli — headless CLI do operacji .fig
- src/commands/ info, tree, find, export, eval, analyze
- mcp/ @open-pencil/mcp — serwer MCP dla narzędzi AI
- src/ Transporty stdio + HTTP (Hono), 87 narzędzi
-src/
- components/ Vue SFCs (canvas, panele, pasek narzędzi, wybieracz kolorów)
- properties/ Sekcje panelu właściwości (Wygląd, Wypełnienie, Obrys, itp.)
- composables/ Wejście canvasu, skróty klawiszowe, hooki renderowania
- stores/ Stan edytora (reaktywność Vue)
- engine/ Shimy re-eksportu z @open-pencil/core
- kiwi/ Shimy re-eksportu z @open-pencil/core
- types.ts Współdzielone typy (re-eksportowane z core)
- constants.ts Kolory UI, wartości domyślne, progi
-desktop/ Tauri v2 (Rust + config)
-tests/
- e2e/ Regresja wizualna Playwright
- engine/ Testy jednostkowe (bun:test)
-docs/ Strona dokumentacji VitePress
- specs/ Specyfikacje możliwości (źródło prawdy)
- changes/ Aktywne i zarchiwizowane zmiany
-```
-
-## Konfiguracja deweloperska
-
-```sh
-bun install
-bun run dev # Edytor na localhost:1420
-bun run docs:dev # Dokumentacja na localhost:5173
-```
-
-## Styl kodu
-
-### Narzędzia
-
-| Narzędzie | Polecenie | Cel |
-|-----------|-----------|-----|
-| oxlint | `bun run lint` | Linting (oparty na Rust, szybki) |
-| oxfmt | `bun run format` | Formatowanie kodu |
-| tsgo | `bun run typecheck` | Sprawdzanie typów (checker TypeScript oparty na Go) |
-
-Uruchom wszystkie sprawdzenia:
-
-```sh
-bun run check
-```
-
-### Konwencje
-
-- **Nazwy plików** — kebab-case (`scene-graph.ts`, `use-canvas-input.ts`)
-- **Komponenty** — PascalCase Vue SFCs (`EditorCanvas.vue`, `NumberField.vue`)
-- **Stałe** — SCREAMING_SNAKE_CASE
-- **Funkcje/zmienne** — camelCase
-- **Typy/interfejsy** — PascalCase
-
-### Konwencje dla agentów AI
-
-Deweloperzy i agenci AI powinni przeczytać `AGENTS.md` w katalogu głównym repo ([zobacz na GitHub](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)). Obejmuje renderowanie, graf sceny, komponenty i instancje, layout, UI, format pliku, konwencje Tauri i znane problemy.
-
-## Wprowadzanie zmian
-
-3. Zaimplementować zmianę
-4. Uruchomić `bun run check` i `bun run test`
-5. Wysłać pull request
-
-## Kluczowe pliki
-
-Kod źródłowy silnika core znajduje się w `packages/core/src/`. Kod aplikacyjny edytora, dokumentów, AI, współpracy, shella, demo i automatyzacji znajduje się w `src/app/*`; SDK Vue zawiera wielokrotnego użytku kod canvasu i composable w `packages/vue/src/`.
-
-| Plik | Cel |
-|------|-----|
-| `packages/scene-graph/src/` | Graf sceny: węzły, zmienne, instancje, hit testing i cofanie |
-| `packages/core/src/canvas/renderer.ts` | Pipeline renderowania CanvasKit |
-| `packages/core/src/layout/` | Adapter layoutu Yoga |
-| `packages/core/src/clipboard.ts` | Schowek kompatybilny z Figmą |
-| `packages/core/src/vector/` | Model sieci wektorowej |
-| `packages/core/src/io/formats/raster/render.ts` | Eksport obrazu offscreen (PNG/JPG/WEBP) |
-| `packages/kiwi/src/schema-runtime/` | Runtime schematu i kodek binarny Kiwi |
-| `packages/fig/src/node-change/` | Konwersja między SceneGraph i Figma NodeChange |
-| `packages/core/src/io/formats/fig/` | Orkiestracja odczytu/zapisu .fig dla aplikacji |
-| `packages/cli/src/index.ts` | Punkt wejścia CLI |
-| `packages/core/src/tools/` | Ujednolicone definicje narzędzi (AI, MCP, CLI) |
-| `packages/core/src/figma-api/` | Implementacja Figma Plugin API |
-| `packages/mcp/src/server.ts` | Fabryka serwera MCP |
-| `packages/cli/src/commands/` | Polecenia CLI (info, tree, find, export, eval, analyze) |
-| `src/app/editor/session/create.ts` | Editor session assembly |
-| `packages/vue/src/canvas/CanvasRoot.vue` | Composable renderowania canvasu |
-| `packages/vue/src/canvas/useCanvasInput.ts` | Obsługa wejścia mysz/dotyk |
-| `src/app/shell/keyboard/use.ts` | Obsługa skrótów klawiszowych |
diff --git a/packages/docs/pl/development/testing.md b/packages/docs/pl/development/testing.md
deleted file mode 100644
index abd34c459..000000000
--- a/packages/docs/pl/development/testing.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# Testowanie
-
-## Przegląd
-
-| Type | Framework | Command | Location |
-|------|-----------|---------|----------|
-| E2E visual regression | Playwright | `bun run test` | `tests/e2e/` |
-| Figma CDP reference | Playwright | `bun run test:figma` | `tests/figma/` |
-| Unit tests | bun:test | `bun run test:unit` | `tests/engine/` |
-
-## Regresja wizualna E2E
-
-```sh
-bun run test # Compare against baselines
-bun run test:update # Regenerate baselines
-```
-
-1. Playwright → headless browser
-2. `data-ready` HTML attribute
-3. Create shapes → screenshot → `toMatchSnapshot`
-
-## Testy referencyjne Figma CDP
-
-```sh
-bun run figma:debug # Launch Figma with debugging port
-bun run test:figma # Connect via CDP
-```
-
-## Testy jednostkowe
-
-```sh
-bun run test:unit
-```
-
-- Scene graph CRUD, hit testing
-- Fig-import pipeline
-- Layout computation (Yoga)
-- MCP server edge cases
-
-## Pokrycie testów E2E
-
-| Test file | Scope |
-|-----------|-------|
-| `tests/e2e/layers-panel.spec.ts` | Layers panel |
-| `tests/e2e/visual.spec.ts` | Visual regression |
-
-## Cele wydajnościowe
-
-| Metric | Target |
-|--------|--------|
-| E2E suite | < 3s |
-| Unit tests | < 50ms |
diff --git a/packages/docs/pl/guide/getting-started.md b/packages/docs/pl/getting-started.md
similarity index 97%
rename from packages/docs/pl/guide/getting-started.md
rename to packages/docs/pl/getting-started.md
index 40120777b..07315d3cd 100644
--- a/packages/docs/pl/guide/getting-started.md
+++ b/packages/docs/pl/getting-started.md
@@ -39,4 +39,4 @@ Otwiera edytor na `http://localhost:1420`.
## Aplikacja desktopowa (Tauri)
-Szczegółowe instrukcje dla każdej platformy w [wersji angielskiej](/guide/getting-started).
+Szczegółowe instrukcje dla każdej platformy w [wersji angielskiej](/getting-started).
diff --git a/packages/docs/pl/guide/architecture.md b/packages/docs/pl/guide/architecture.md
deleted file mode 100644
index 06149e48d..000000000
--- a/packages/docs/pl/guide/architecture.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# Architektura
-
-## Przegląd systemu
-
-`mermaid
-graph TB
- subgraph Tauri["Tauri v2 Shell"]
- subgraph Editor["Editor (Web)"]
- UI["Vue 3 UI<br/>Toolbar · Panels · Properties<br/>Layers · Color Picker"]
- Skia["Skia CanvasKit (WASM, 7MB)<br/>Vector rendering · Text shaping<br/>Effects · Export"]
- subgraph Core["Core Engine (TS)"]
- SG[SceneGraph] --- Layout[Layout - Yoga]
- SG --- Selection
- Undo[Undo/Redo] --- Constraints
- Constraints --- HitTest[Hit Testing]
- end
- subgraph FileFormat["File Format Layer"]
- FigIO[".fig import/export"] --- Kiwi[Kiwi codec]
- Kiwi --- SVG[SVG export]
- end
- end
- MCP["MCP Server (90 tools, stdio+HTTP)"]
- Collab["P2P Collab (Trystero + Yjs)"]
- end
-`
-
-## Układ edytora
-
-Interfejs podąża za layoutem UI3 Figmy — pasek narzędzi na dole, nawigacja po lewej, właściwości po prawej:
-
-- **Panel nawigacji (lewy)** — Drzewo warstw, panel stron
-- **Canvas (środek)** — Nieskończony canvas z renderowaniem CanvasKit, zoom/pan
-- **Panel właściwości (prawy)** — Kontekstowe sekcje: Wygląd, Wypełnienie, Obrys, Typografia, Layout, Pozycja
-- **Pasek narzędzi (dół)** — Wybór narzędzia: Zaznacz, Frame, Sekcja, Prostokąt, Elipsa, Linia, Tekst, Pióro, Ręka
-
-## Komponenty
-
-### Renderowanie (CanvasKit WASM)
-
-Ten sam silnik renderowania co Figma. CanvasKit zapewnia rysowanie 2D z akceleracją GPU z kształtami wektorowymi, kształtowaniem tekstu przez Paragraph API, efektami (cienie, rozmycia, tryby mieszania) i eksportem (PNG, SVG). Binarny plik WASM o wielkości 7 MB ładuje się przy starcie i tworzy powierzchnię GPU na canvasie HTML.
-
-Renderer jest podzielony na wyspecjalizowane moduły w `packages/core/src/renderer/`: przechodzenie sceny, nakładki, wypełnienia, obrysy, kształty, efekty, linijki, etykiety i zdalne kursory.
-
-### Graf sceny
-
-Płaska `Map<string, Node>` indeksowana ciągami GUID. Struktura drzewa poprzez referencje `parentIndex`. Zapewnia wyszukiwanie O(1), wydajne przechodzenie, hit testing i zapytania obszarowe dla selekcji markerowej.
-
-Graf emituje typowane zdarzenia przez nanoevents: `node:created`, `node:updated`, `node:deleted`, `node:reparented`, `node:reordered`. Podsystemy subskrybują te zdarzenia zamiast ręcznego okablowania — edytor używa ich do unieważniania renderowania i synchronizacji instancji komponentów z microtask batchingiem, system współpracy do propagacji Yjs.
-
-Zobacz [Referencja grafu sceny](/reference/scene-graph) dla szczegółów wewnętrznych.
-
-### Silnik layoutu (Yoga WASM)
-
-Yoga od Mety zapewnia obliczanie layoutu CSS flexbox i grid poprzez [fork](https://github.com/open-pencil/yoga/tree/grid) z obsługą CSS Grid. Cienki adapter mapuje nazwy właściwości Figmy na odpowiedniki Yoga:
-
-| Właściwość Figma | Odpowiednik Yoga |
-|---|---|
-| `stackMode: HORIZONTAL` | `flexDirection: row` |
-| `stackMode: VERTICAL` | `flexDirection: column` |
-| `stackSpacing` | `gap` |
-| `stackPadding` | `padding` |
-| `stackJustify` | `justifyContent` |
-| `stackChildPrimaryGrow` | `flexGrow` |
-
-### Format pliku (Kiwi binarny)
-
-Wykorzystuje binarny kodek Kiwi Figmy z 194 definicjami wiadomości/enum/struct. Import: parsowanie nagłówka → dekompresja Zstd → dekodowanie Kiwi → `NodeChange`[] → graf sceny. Eksport odwraca proces z generowaniem miniatur.
-
-Zobacz [Referencja formatu pliku](/reference/file-format) dla szczegółów.
-
-### AI i narzędzia
-
-Narzędzia są definiowane raz w `packages/core/src/tools/`, podzielone wg domeny: read, create, modify, structure, variables, vector, analyze. Każde narzędzie ma typowane parametry i funkcję `execute(figma, args)`. Adaptery konwertują je dla:
-
-- **Chat AI** — schematy valibot, multi-provider (Anthropic, OpenAI, Google AI, OpenRouter, kompatybilne endpointy)
-- **Serwer MCP** — schematy zod, transporty stdio + HTTP
-- **CLI** — dostępne przez komendę `eval`
-
-90+ narzędzi core + 3 narzędzia zarządzania plikami MCP. Zawiera zapytania XPath (`query_nodes`), inspekcję JSX (`get_jsx`, `diff_jsx`), opis semantyczny (`describe`) i weryfikację wizualną (`export_image` zwraca obrazy do modelu).
-
-### Cofnij/Ponów
-
-Wzorzec komendy odwrotnej. Przed zastosowaniem jakiejkolwiek zmiany, dotknięte pola są zrzucane do snapshotu. Snapshot staje się operacją odwrotną. Batching grupuje szybkie zmiany (jak przeciąganie) w pojedyncze wpisy cofania.
-
-### Schowek
-
-Dwukierunkowy schowek kompatybilny z Figmą. Koduje/dekoduje binarne Kiwi (ten sam format co pliki .fig) przez natywne zdarzenia kopiuj/wklej przeglądarki. Obsługuje skalowanie ścieżek wektorowych, dzieci instancji, wykrywanie zestawów komponentów i stosowanie nadpisań.
-
-### Współpraca P2P
-
-Współpraca peer-to-peer w czasie rzeczywistym przez Trystero (WebRTC) + Yjs CRDT. Bez serwera relay — sygnalizacja przez publiczne brokery MQTT, STUN/TURN dla traversalu NAT. Protokół awareness zapewnia kursory na żywo, selekcje i obecność. Lokalna persystencja przez y-indexeddb.
-
-### Most RPC CLI-do-Aplikacji
-
-Gdy aplikacja desktopowa jest uruchomiona, komendy CLI łączą się z nią przez WebSocket zamiast wymagać pliku .fig. Serwer automatyzacji działa na `127.0.0.1:7600` (HTTP) i `127.0.0.1:7601` (WebSocket). Komendy wykonują się na stanie edytora na żywo, umożliwiając skryptom automatyzacji i agentom AI interakcję z uruchomioną aplikacją.
-
-## Co dalej
-
-### Pełny zestaw narzędzi figma-use
-
-Serwer MCP obecnie udostępnia 90 narzędzi. Referencyjna implementacja w [figma-use](https://github.com/dannote/figma-use) ma 118. Pozostałe narzędzia obejmują zaawansowane ograniczenia layoutu, połączenia prototypów, zaawansowaną edycję właściwości komponentów i masowe operacje na dokumentach.
-
-### Narzędzia CI do designu
-
-Headless CLI już obsługuje `analyze colors/typography/spacing/clusters`. Następnie: integracja z GitHub Actions dla automatycznego lintingu designu i regresji wizualnej w PR-ach.
-
-### Prototypowanie
-
-Przejścia między ramkami, wyzwalacze interakcji (kliknięcie, najechanie, przeciągnięcie), zarządzanie nakładkami i tryb podglądu pełnoekranowego.
-
-### Podpisywanie kodu Windows
-
-Binaria macOS są podpisane i notaryzowane od v0.6.0. Podpisywanie Windows Authenticode przez Azure Code Signing jest planowane aby usunąć ostrzeżenie SmartScreen.
diff --git a/packages/docs/pl/guide/tech-stack.md b/packages/docs/pl/guide/tech-stack.md
deleted file mode 100644
index c2bfe4fc9..000000000
--- a/packages/docs/pl/guide/tech-stack.md
+++ /dev/null
@@ -1,71 +0,0 @@
-# Stack technologiczny
-
-## Główne technologie
-
-| Warstwa | Technologia | Dlaczego |
-|---------|-----------|----------|
-| **Renderowanie** | Skia CanvasKit WASM | Ten sam silnik co Figma — sprawdzona wydajność, akceleracja GPU, idealny piksel |
-| **Framework UI** | Vue 3 + VueUse | Reaktywne API kompozycji, doskonałe wsparcie TypeScript |
-| **Komponenty** | Reka UI | Bezgłowe, dostępne prymitywy UI (drzewo, suwak, itp.) |
-| **Stylowanie** | Tailwind CSS 4 | Utility-first, szybka iteracja, ciemny motyw |
-| **Layout** | Yoga WASM | Silnik CSS flexbox od Mety, sprawdzony w React Native |
-| **Format pliku** | Kiwi binarny + Zstd | Własny format Figmy — kompaktowy, szybkie parsowanie, kompatybilny z .fig |
-| **Współpraca** | Trystero + Yjs | P2P WebRTC przez sygnalizację MQTT, sync CRDT, persystencja y-indexeddb |
-| **Kolor** | culori | Konwersje przestrzeni kolorów (HSV, RGB, hex) |
-| **AI/MCP** | MCP SDK + Hono | 90+ narzędzi dla kodowania AI, transporty stdio + HTTP |
-| **JSX Transform** | Sucrase | 201 KB JSX → JS, synchroniczny, kompatybilny z przeglądarką |
-| **Zdarzenia** | nanoevents | 108 bajtów, typowany emitter zdarzeń dla mutacji SceneGraph |
-| **JSX Transform** | Sucrase | 201 KB JSX → JS, synchroniczny, kompatybilny z przeglądarką |
-| **Zdarzenia** | nanoevents | 108 bajtów, typowany emitter zdarzeń dla mutacji SceneGraph |
-| **JSX Transform** | Sucrase | Lightweight (201 KB) JSX → JS, synchronous, browser-compatible |
-| **Events** | nanoevents | 108 bytes, typed event emitter for SceneGraph mutations |
-| **Desktop** | Tauri v2 | ~5 MB natywna aplikacja (vs ~100 MB Electrona), backend Rust |
-| **Build** | Vite 7 | Szybki HMR, natywne moduły ES |
-| **Testowanie** | Playwright + bun:test | Regresja wizualna (E2E) + szybkie testy jednostkowe |
-| **Linting** | oxlint | Oparty na Rust, rzędy wielkości szybszy niż ESLint |
-| **Formatowanie** | oxfmt | Formater oparty na Rust |
-| **Weryfikacja typów** | typescript-go (tsgo) | Natywna implementacja w Go sprawdzania typów TypeScript |
-
-## Główne zależności
-
-```json
-{
- "canvaskit-wasm": "^0.40.0",
- "vue": "^3.5.29",
- "yoga-layout": "npm:@open-pencil/[email protected]",
- "nanoevents": "^9.1.0",
- "sucrase": "^3.35.1",
- "reka-ui": "^2.8.2",
- "tailwindcss": "^4.2.1",
- "culori": "^4.0.2",
- "fzstd": "^0.1.1",
- "fflate": "^0.8.2",
- "trystero": "^0.20.0",
- "yjs": "^13.6.24",
- "y-indexeddb": "^9.0.12"
-}
-```
-
-## Dlaczego nie...
-
-### Dlaczego nie renderowanie SVG?
-
-SVG jest wolny dla złożonych dokumentów. Każdy węzeł to element DOM — 10 000 węzłów oznacza 10 000 elementów DOM z narzutem layoutu, rysowania i kompozycji. CanvasKit rysuje wszystko na jednej powierzchni GPU.
-
-### Dlaczego nie Electron (jak Figma desktop)?
-
-Tauri v2 używa systemowego webview (~5 MB) zamiast pakowania Chromium (~100 MB). Backend Rust zapewnia natywną wydajność dla I/O plików i integracji systemowej.
-
-### Dlaczego nie React?
-
-Projekt migrował z Reacta do Vue 3 na wczesnym etapie. System reaktywności Vue i composable VueUse okazały się bardziej ergonomiczne.
-
-### Dlaczego nie własny silnik layoutu?
-
-Yoga jest utrzymywana przez Metę, przetestowana na miliardach urządzeń React Native i implementuje specyfikację CSS flexbox.
-
-## Planowane technologie
-
-| Technologia | Cel | Faza |
-|-----------|---------|-------|
-| CSS Grid w Yoga | Auto layout oparty na siatce | ✅ Obsługiwane przez [fork Yoga](https://github.com/open-pencil/yoga/tree/grid) (`@open-pencil/yoga-layout`) |
diff --git a/packages/docs/pl/guide/comparison.md b/packages/docs/pl/overview/comparison.md
similarity index 100%
rename from packages/docs/pl/guide/comparison.md
rename to packages/docs/pl/overview/comparison.md
diff --git a/packages/docs/pl/guide/features.md b/packages/docs/pl/overview/features.md
similarity index 100%
rename from packages/docs/pl/guide/features.md
rename to packages/docs/pl/overview/features.md
diff --git a/packages/docs/pl/programmable/index.md b/packages/docs/pl/programmable/index.md
index 827f59ffc..a940d26c0 100644
--- a/packages/docs/pl/programmable/index.md
+++ b/packages/docs/pl/programmable/index.md
@@ -12,7 +12,7 @@ Interfejs edytora i interfejsy automatyzacji korzystają z tego samego silnika.
## Czat AI
-Wbudowany asystent ma dostęp do 87 narzędzi, które obejmują całą powierzchnię edytora. Opisz czego chcesz w języku naturalnym — „dodaj cień 16px do wszystkich przycisków", „utwórz komponent karty z wariantem ciemnego motywu", „wyeksportuj każdą ramkę na tej stronie w 2×".
+Wbudowany asystent ma dostęp do ponad 90 narzędzi, które obejmują całą powierzchnię edytora. Opisz czego chcesz w języku naturalnym — „dodaj cień 16px do wszystkich przycisków", „utwórz komponent karty z wariantem ciemnego motywu", „wyeksportuj każdą ramkę na tej stronie w 2×".
[Czat AI →](./ai-chat)
diff --git a/packages/docs/pl/guide/figma-comparison.md b/packages/docs/pl/reference/figma-compatibility.md
similarity index 99%
rename from packages/docs/pl/guide/figma-comparison.md
rename to packages/docs/pl/reference/figma-compatibility.md
index f9dd0d6a3..81a20c183 100644
--- a/packages/docs/pl/guide/figma-comparison.md
+++ b/packages/docs/pl/reference/figma-compatibility.md
@@ -215,7 +215,7 @@ Porównanie funkcja po funkcji możliwości Figma Design z aktualnym stanem impl
| Code Connect | 🔲 | Łączenie komponentów projektowych z kodem |
| Fragmenty kodu | 🟡 | Eksport JSX z podświetlaniem i kopiowaniem; brak fragmentów CSS/Swift/Kotlin |
| Figma for VS Code | 🔲 | Integracja z pluginem edytora |
-| Serwer MCP | ✅ | @open-pencil/mcp z transportami stdio + HTTP; 87 narzędzi core + 3 zarządzanie plikami = 90+ total |
+| Serwer MCP | ✅ | @open-pencil/mcp z transportami stdio i HTTP oraz ponad 90 narzędziami, w tym operacjami na plikach |
| Narzędzia CLI | ✅ | Headless CLI: info, tree, find, export, analyze, node, pages, variables, eval; serwer MCP |
## Figma Draw
diff --git a/packages/docs/programmable/index.md b/packages/docs/programmable/index.md
index fe2ff1ea9..6a49babe3 100644
--- a/packages/docs/programmable/index.md
+++ b/packages/docs/programmable/index.md
@@ -20,7 +20,7 @@ That is why the automation surface matters. The app, the CLI, the AI tools, the
## AI Chat
-The built-in assistant has access to 87 tools that cover the full surface of the editor. Describe what you want in natural language — "add a 16px drop shadow to all buttons", "create a card component with dark mode variant", "export every frame on this page at 2×".
+The built-in assistant has access to 90+ tools that cover the full surface of the editor. Describe what you want in natural language — "add a 16px drop shadow to all buttons", "create a card component with dark mode variant", "export every frame on this page at 2×".
[AI Chat →](./ai-chat)
diff --git a/packages/docs/public/_redirects b/packages/docs/public/_redirects
new file mode 100644
index 000000000..c59f31b8f
--- /dev/null
+++ b/packages/docs/public/_redirects
@@ -0,0 +1,45 @@
+# Legacy documentation routes
+/guide/getting-started /getting-started 301
+/guide/features /overview/features 301
+/guide/architecture /development/architecture 301
+/guide/tech-stack /development/tech-stack 301
+/guide/comparison /overview/comparison 301
+/guide/figma-comparison /reference/figma-compatibility 301
+
+# Localized legacy documentation routes
+/de/guide/getting-started /de/getting-started 301
+/de/guide/features /de/overview/features 301
+/de/guide/architecture /development/architecture 301
+/de/guide/tech-stack /development/tech-stack 301
+/de/guide/comparison /de/overview/comparison 301
+/de/guide/figma-comparison /de/reference/figma-compatibility 301
+/es/guide/getting-started /es/getting-started 301
+/es/guide/features /es/overview/features 301
+/es/guide/architecture /development/architecture 301
+/es/guide/tech-stack /development/tech-stack 301
+/es/guide/comparison /es/overview/comparison 301
+/es/guide/figma-comparison /es/reference/figma-compatibility 301
+/fr/guide/getting-started /fr/getting-started 301
+/fr/guide/features /fr/overview/features 301
+/fr/guide/architecture /development/architecture 301
+/fr/guide/tech-stack /development/tech-stack 301
+/fr/guide/comparison /fr/overview/comparison 301
+/fr/guide/figma-comparison /fr/reference/figma-compatibility 301
+/it/guide/getting-started /it/getting-started 301
+/it/guide/features /it/overview/features 301
+/it/guide/architecture /development/architecture 301
+/it/guide/tech-stack /development/tech-stack 301
+/it/guide/comparison /it/overview/comparison 301
+/it/guide/figma-comparison /it/reference/figma-compatibility 301
+/pl/guide/getting-started /pl/getting-started 301
+/pl/guide/features /pl/overview/features 301
+/pl/guide/architecture /development/architecture 301
+/pl/guide/tech-stack /development/tech-stack 301
+/pl/guide/comparison /pl/overview/comparison 301
+/pl/guide/figma-comparison /pl/reference/figma-compatibility 301
+/ru/guide/getting-started /ru/getting-started 301
+/ru/guide/features /ru/overview/features 301
+/ru/guide/architecture /development/architecture 301
+/ru/guide/tech-stack /development/tech-stack 301
+/ru/guide/comparison /ru/overview/comparison 301
+/ru/guide/figma-comparison /ru/reference/figma-compatibility 301
diff --git a/packages/docs/guide/figma-comparison.md b/packages/docs/reference/figma-compatibility.md
similarity index 100%
rename from packages/docs/guide/figma-comparison.md
rename to packages/docs/reference/figma-compatibility.md
diff --git a/packages/docs/ru/development/contributing.md b/packages/docs/ru/development/contributing.md
deleted file mode 100644
index 7a06dd2fa..000000000
--- a/packages/docs/ru/development/contributing.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# Участие в разработке
-
-## Структура проекта
-
-```
-packages/
- core/ @open-pencil/core — движок (без DOM-зависимостей)
- src/ Граф сцены, отрисовщик, компоновка, кодек, kiwi, типы
- cli/ @open-pencil/cli — headless CLI для операций с .fig
- src/commands/ info, tree, find, export, eval, analyze
- mcp/ @open-pencil/mcp — MCP-сервер для AI-инструментов
- src/ stdio + HTTP (Hono) транспорты, 87 инструментов
-src/
- components/ Vue SFC (холст, панели, панель инструментов, палитра цветов)
- properties/ Секции панели свойств (Внешний вид, Заливка, Обводка и др.)
- composables/ Ввод на холсте, сочетания клавиш, хуки отрисовки
- stores/ Состояние редактора (реактивность Vue)
- engine/ Шимы реэкспорта из @open-pencil/core
- kiwi/ Шимы реэкспорта из @open-pencil/core
- types.ts Общие типы (реэкспорт из core)
- constants.ts Цвета UI, значения по умолчанию, пороги
-desktop/ Tauri v2 (Rust + конфигурация)
-tests/
- e2e/ Визуальная регрессия Playwright
- engine/ Юнит-тесты (bun:test)
-docs/ Сайт документации VitePress
- specs/ Спецификации возможностей (источник истины)
- changes/ Активные и архивные изменения
-```
-
-## Настройка среды разработки
-
-```sh
-bun install
-bun run dev # Редактор на localhost:1420
-bun run docs:dev # Документация на localhost:5173
-```
-
-## Стиль кода
-
-### Инструменты
-
-| Инструмент | Команда | Назначение |
-|------------|---------|------------|
-| oxlint | `bun run lint` | Линтинг (на Rust, быстрый) |
-| oxfmt | `bun run format` | Форматирование кода |
-| tsgo | `bun run typecheck` | Проверка типов (TypeScript-чекер на Go) |
-
-Запуск всех проверок:
-
-```sh
-bun run check
-```
-
-### Соглашения
-
-- **Имена файлов** — kebab-case (`scene-graph.ts`, `use-canvas-input.ts`)
-- **Компоненты** — PascalCase Vue SFC (`EditorCanvas.vue`, `NumberField.vue`)
-- **Константы** — SCREAMING_SNAKE_CASE
-- **Функции/переменные** — camelCase
-- **Типы/интерфейсы** — PascalCase
-
-### Соглашения для AI-агентов
-
-Разработчики и AI-агенты, работающие с кодовой базой, должны прочитать `AGENTS.md` в корне репозитория ([посмотреть на GitHub](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)). Файл охватывает отрисовку, граф сцены, компоненты и экземпляры, компоновку, UI, формат файлов, соглашения Tauri и известные проблемы.
-
-## Внесение изменений
-
-3. Реализуйте изменение
-4. Запустите `bun run check` и `bun run test`
-5. Создайте pull request
-
-## Ключевые файлы
-
-Исходники core-движка находятся в `packages/core/src/`. Код приложения для редактора, документов, AI, коллаборации, shell, демо и автоматизации живёт в `src/app/*`; Vue SDK содержит переиспользуемый canvas/composable-код в `packages/vue/src/`.
-
-| Файл | Назначение |
-|------|------------|
-| `packages/scene-graph/src/` | Граф сцены: узлы, переменные, экземпляры, проверка попадания и отмена |
-| `packages/core/src/canvas/renderer.ts` | Конвейер отрисовки CanvasKit |
-| `packages/core/src/layout/` | Адаптер компоновки Yoga |
-| `packages/core/src/clipboard.ts` | Figma-совместимый буфер обмена |
-| `packages/core/src/vector/` | Модель векторных сетей |
-| `packages/core/src/io/formats/raster/render.ts` | Внеэкранный экспорт изображений (PNG/JPG/WEBP) |
-| `packages/kiwi/src/schema-runtime/` | Среда схемы и бинарный кодек Kiwi |
-| `packages/fig/src/node-change/` | Преобразование SceneGraph и Figma NodeChange |
-| `packages/core/src/io/formats/fig/` | Оркестрация чтения и записи .fig для приложения |
-| `packages/cli/src/index.ts` | Точка входа CLI |
-| `packages/core/src/tools/` | Унифицированные определения инструментов по доменам (read, create, modify, structure, variables, vector, analyze) |
-| `packages/core/src/figma-api/` | Реализация Figma Plugin API |
-| `packages/mcp/src/server.ts` | Фабрика MCP-сервера |
-| `packages/cli/src/commands/` | Команды CLI (info, tree, find, export, eval, analyze) |
-| `src/app/editor/session/create.ts` | Editor session assembly |
-| `packages/vue/src/canvas/CanvasRoot.vue` | Composable отрисовки холста |
-| `packages/vue/src/canvas/useCanvasInput.ts` | Обработка ввода мышью/тачем |
-| `src/app/shell/keyboard/use.ts` | Обработка сочетаний клавиш |
diff --git a/packages/docs/ru/development/testing.md b/packages/docs/ru/development/testing.md
deleted file mode 100644
index 673b321e3..000000000
--- a/packages/docs/ru/development/testing.md
+++ /dev/null
@@ -1,92 +0,0 @@
-# Тестирование
-
-## Обзор
-
-| Тип | Фреймворк | Команда | Расположение |
-| ------------------------ | ---------- | -------------------- | --------------- |
-| E2E визуальная регрессия | Playwright | `bun run test` | `tests/e2e/` |
-| Figma CDP референс | Playwright | `bun run test:figma` | `tests/figma/` |
-| Юнит-тесты | bun:test | `bun run test:unit` | `tests/engine/` |
-
-## E2E визуальная регрессия
-
-Playwright создаёт фигуры на холсте и сравнивает скриншоты с эталонными PNG.
-
-```sh
-bun run test # Запуск тестов, сравнение с эталонами
-bun run test:update # Пересоздание эталонных скриншотов
-```
-
-### Как это работает
-
-1. Тесты загружают редактор в headless-браузере
-2. Редактор сигнализирует о готовности через HTML-атрибут `data-ready`
-3. Тесты создают фигуры через API редактора
-4. Скриншоты снимаются и сравниваются с эталонами с помощью `toMatchSnapshot`
-5. Страница переиспользуется между тест-кейсами для скорости (~2с на все)
-
-### Режим без оформления
-
-Редактор поддерживает тестовый режим, скрывающий элементы интерфейса (панель инструментов, панели) для чистого снятия скриншотов. Активируется через URL-параметр.
-
-## Figma CDP референсные тесты
-
-Отдельный Playwright-проект подключается к Figma через Chrome DevTools Protocol для снятия эталонных скриншотов для попиксельного сравнения.
-
-```sh
-bun run figma:debug # Запустить Figma с портом отладки
-bun run test:figma # Подключиться к Figma, снять эталоны
-```
-
-Требуется запущенное десктопное приложение Figma с `--remote-debugging-port=9222`.
-
-## Юнит-тесты
-
-Юнит-тесты движка используют bun:test и нацелены на время выполнения < 50мс:
-
-```sh
-bun run test:unit
-```
-
-Тесты покрывают:
-
-- CRUD-операции графа сцены, связи родитель-потомок, z-упорядочивание, проверку попадания
-- **Конвейер fig-import** — маппинг типов узлов, трансформации, заливки/обводки/эффекты, градиенты, изображения, дуги, вложенные иерархии (`tests/engine/io/fig/import/legacy/*.test.ts`)
-- **Вычисление компоновки** — Yoga auto-layout: направление, gap, padding, justify, align, размер потомков (fixed/fill/hug), размер по поперечной оси, перенос, вложенные компоновки (`tests/engine/layout/`)
-
-### Написание юнит-тестов
-
-```typescript
-import { describe, expect, it } from 'bun:test'
-import { SceneGraph } from '@open-pencil/scene-graph'
-
-describe('SceneGraph', () => {
- it('creates and retrieves a node', () => {
- const sg = new SceneGraph()
- const node = sg.createNode('RECTANGLE', sg.root, { name: 'Test' })
- expect(sg.getNode(node.guid)).toBeDefined()
- })
-})
-```
-
-## Покрытие E2E-тестами
-
-| Файл теста | Область |
-| -------------------------------- | ------------------------------------------------------------------------------------ |
-| `tests/e2e/layers-panel.spec.ts` | Древовидная структура панели слоёв, переключатели видимости, синхронизация выделения |
-| `tests/e2e/visual.spec.ts` | Визуальная регрессия скриншотов для фигур и отрисовки |
-
-## Вспомогательные модули
-
-| Файл | Назначение |
-| ------------------------- | -------------------------------------------- |
-| `tests/helpers/canvas.ts` | Утилиты настройки и взаимодействия с холстом |
-| `tests/helpers/figma.ts` | Хелперы подключения к Figma по CDP |
-
-## Целевые показатели производительности
-
-| Метрика | Цель |
-| ------------------------ | ----------------------------- |
-| Полный E2E-набор | < 3с |
-| Полный набор юнит-тестов | < 50мс |
-| Сравнение скриншотов | toMatchSnapshot (попиксельно) |
diff --git a/packages/docs/ru/guide/getting-started.md b/packages/docs/ru/getting-started.md
similarity index 94%
rename from packages/docs/ru/guide/getting-started.md
rename to packages/docs/ru/getting-started.md
index 8ba2b03ca..01710174c 100644
--- a/packages/docs/ru/guide/getting-started.md
+++ b/packages/docs/ru/getting-started.md
@@ -59,7 +59,8 @@ bun run dev
| `bun run test:update` | Перегенерация эталонных скриншотов |
| `bun run test:unit` | Модульные тесты (bun:test) |
| `bun run docs:dev` | Сервер документации |
-| `bun run docs:build` | Сборка сайта документации |
+| `bun run docs:build` | Быстрая локальная сборка документации |
+| `bun run docs:build:production` | Полная сборка документации для развёртывания |
## Десктоп-приложение (Tauri)
diff --git a/packages/docs/ru/guide/architecture.md b/packages/docs/ru/guide/architecture.md
deleted file mode 100644
index 62d17f934..000000000
--- a/packages/docs/ru/guide/architecture.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# Архитектура
-
-## Обзор системы
-
-`mermaid
-graph TB
- subgraph Tauri["Tauri v2 Shell"]
- subgraph Editor["Editor (Web)"]
- UI["Vue 3 UI<br/>Toolbar · Panels · Properties<br/>Layers · Color Picker"]
- Skia["Skia CanvasKit (WASM, 7MB)<br/>Vector rendering · Text shaping<br/>Effects · Export"]
- subgraph Core["Core Engine (TS)"]
- SG[SceneGraph] --- Layout[Layout - Yoga]
- SG --- Selection
- Undo[Undo/Redo] --- Constraints
- Constraints --- HitTest[Hit Testing]
- end
- subgraph FileFormat["File Format Layer"]
- FigIO[".fig import/export"] --- Kiwi[Kiwi codec]
- Kiwi --- SVG[SVG export]
- end
- end
- MCP["MCP Server (90 tools, stdio+HTTP)"]
- Collab["P2P Collab (Trystero + Yjs)"]
- end
-`
-
-## Макет редактора
-
-Интерфейс следует макету Figma UI3 — панель инструментов внизу, навигация слева, свойства справа:
-
-- **Панель навигации (слева)** — Дерево слоёв, панель страниц
-- **Канвас (центр)** — Бесконечный холст с рендерингом CanvasKit, масштабирование/панорамирование
-- **Панель свойств (справа)** — Контекстно-зависимые секции: Внешний вид, Заливка, Обводка, Типографика, Макет, Позиция
-- **Панель инструментов (внизу)** — Выбор инструмента: Выделение, Фрейм, Секция, Прямоугольник, Эллипс, Линия, Текст, Перо, Рука
-
-## Компоненты
-
-### Рендеринг (CanvasKit WASM)
-
-Тот же движок рендеринга, что и у Figma. CanvasKit обеспечивает GPU-ускоренную 2D-отрисовку с векторными фигурами, формирование текста через Paragraph API, эффекты (тени, размытия, режимы наложения) и экспорт (PNG, SVG). WASM-бинарник размером 7 МБ загружается при запуске и создаёт GPU-поверхность на HTML-канвасе.
-
-Рендерер разбит на специализированные модули в `packages/core/src/renderer/`: обход сцены, оверлеи, заливки, обводки, фигуры, эффекты, линейки, подписи и удалённые курсоры.
-
-### Граф сцены
-
-Плоская `Map<string, Node>` с ключами в виде строк GUID. Древовидная структура через ссылки `parentIndex`. Обеспечивает O(1) поиск, эффективный обход, проверку попадания и запросы по прямоугольным областям для выделения рамкой.
-
-Граф порождает типизированные события через nanoevents: `node:created`, `node:updated`, `node:deleted`, `node:reparented`, `node:reordered`. Подсистемы подписываются на них вместо ручной привязки — редактор использует их для инвалидации рендера и синхронизации экземпляров компонентов с группировкой через microtask, система совместной работы — для распространения через Yjs.
-
-См. [справочник графа сцены](/reference/scene-graph) для подробностей.
-
-### Движок макетов (Yoga WASM)
-
-Yoga от Meta обеспечивает вычисление макета CSS flexbox и grid через [форк](https://github.com/open-pencil/yoga/tree/grid) с поддержкой CSS Grid. Тонкий адаптер сопоставляет имена свойств Figma с эквивалентами Yoga:
-
-| Свойство Figma | Эквивалент Yoga |
-|---|---|
-| `stackMode: HORIZONTAL` | `flexDirection: row` |
-| `stackMode: VERTICAL` | `flexDirection: column` |
-| `stackSpacing` | `gap` |
-| `stackPadding` | `padding` |
-| `stackJustify` | `justifyContent` |
-| `stackChildPrimaryGrow` | `flexGrow` |
-
-### Формат файлов (Kiwi Binary)
-
-Использует бинарный кодек Kiwi от Figma с 194 определениями message/enum/struct. Импорт: разбор заголовка → декомпрессия Zstd → декодирование Kiwi → `NodeChange`[] → граф сцены. Экспорт выполняет обратный процесс с генерацией миниатюры.
-
-См. [справочник формата файлов](/reference/file-format) для подробностей.
-
-### ИИ и инструменты
-
-Инструменты определяются один раз в `packages/core/src/tools/`, разделённые по доменам: read, create, modify, structure, variables, vector, analyze. У каждого инструмента типизированные параметры и функция `execute(figma, args)`. Адаптеры конвертируют их для:
-
-- **ИИ-чат** — схемы valibot, мультипровайдер (Anthropic, OpenAI, Google AI, OpenRouter, совместимые эндпоинты)
-- **MCP-сервер** — схемы zod, транспорты stdio + HTTP
-- **CLI** — доступно через команду `eval`
-
-90+ основных инструментов + 3 инструмента управления файлами MCP. Включает XPath-запросы (`query_nodes`), инспекцию JSX (`get_jsx`, `diff_jsx`), семантическое описание (`describe`) и визуальную проверку (`export_image` возвращает изображения модели).
-
-### Отмена/Повтор
-
-Паттерн обратных команд. Перед применением любого изменения затронутые поля сохраняются в снимок. Снимок становится обратной операцией. Группировка объединяет быстрые изменения (например, перетаскивание) в одну запись отмены.
-
-### Буфер обмена
-
-Двусторонний буфер обмена, совместимый с Figma. Кодирует/декодирует бинарный формат Kiwi (тот же, что и файлы .fig) через нативные события copy/paste браузера. Обрабатывает масштабирование векторных путей, дочерние элементы экземпляров, определение наборов компонентов и применение переопределений.
-
-### P2P-совместная работа
-
-Совместная работа в реальном времени через Trystero (WebRTC) + Yjs CRDT. Без серверного реле — сигнализация через публичные MQTT-брокеры, STUN/TURN для обхода NAT. Протокол Awareness обеспечивает живые курсоры, выделения и присутствие. Локальное сохранение через y-indexeddb.
-
-### RPC-мост CLI—приложение
-
-Когда запущено десктоп-приложение, команды CLI подключаются к нему по WebSocket вместо загрузки файла .fig. Сервер автоматизации работает на `127.0.0.1:7600` (HTTP) и `127.0.0.1:7601` (WebSocket). Команды выполняются относительно состояния живого редактора, позволяя скриптам автоматизации и ИИ-агентам взаимодействовать с запущенным приложением.
-
-## Что дальше
-
-### Полный набор инструментов figma-use
-
-MCP-сервер сейчас предоставляет 90 инструментов. Референсная реализация в [figma-use](https://github.com/dannote/figma-use) содержит 118. Оставшиеся инструменты охватывают продвинутые ограничения макета, прототипные связи, расширенное редактирование свойств компонентов и массовые операции с документами.
-
-### CI-инструменты для дизайна
-
-Headless CLI уже поддерживает `analyze colors/typography/spacing/clusters`. Далее: интеграция с GitHub Actions для автоматического линтинга дизайна и визуальной регрессии в пулл-реквестах.
-
-### Прототипирование
-
-Переходы между фреймами, триггеры взаимодействия (клик, наведение, перетаскивание), управление оверлеями и полноэкранный режим предпросмотра.
-
-### Подпись кода для Windows
-
-Бинарные файлы macOS подписаны и нотаризованы с версии v0.6.0. Подпись Windows Authenticode через Azure Code Signing планируется для устранения предупреждения SmartScreen.
diff --git a/packages/docs/ru/guide/tech-stack.md b/packages/docs/ru/guide/tech-stack.md
deleted file mode 100644
index eaa384be6..000000000
--- a/packages/docs/ru/guide/tech-stack.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# Технологический стек
-
-## Ключевые технологии
-
-| Уровень | Технология | Почему |
-|-------|-----------|-----|
-| **Рендеринг** | Skia CanvasKit WASM | Тот же движок, что и у Figma — проверенная производительность, GPU-ускорение, пиксельная точность |
-| **UI-фреймворк** | Vue 3 + VueUse | Реактивный Composition API, отличная поддержка TypeScript |
-| **Компоненты** | Reka UI | Headless, доступные UI-примитивы (дерево, слайдер и т.д.) |
-| **Стилизация** | Tailwind CSS 4 | Утилитарный подход, быстрая итерация, тёмная тема |
-| **Макет** | Yoga WASM | CSS flexbox движок от Meta, проверенный на React Native |
-| **Формат файлов** | Kiwi binary + Zstd | Собственный формат Figma — компактный, быстрый парсинг, совместимость с .fig |
-| **Совместная работа** | Trystero + Yjs | P2P WebRTC через MQTT, CRDT-синхронизация, сохранение в y-indexeddb |
-| **Цвет** | culori | Конвертация цветовых пространств (HSV, RGB, hex) |
-| **ИИ/MCP** | MCP SDK + Hono | 90+ инструментов для ИИ-кодинга, транспорты stdio + HTTP |
-| **JSX-трансформ** | Sucrase | 201 КБ JSX → JS, синхронный, работает в браузере |
-| **События** | nanoevents | 108 байт, типизированный эмиттер событий для мутаций SceneGraph |
-| **JSX-трансформ** | Sucrase | 201 КБ JSX → JS, синхронный, работает в браузере |
-| **События** | nanoevents | 108 байт, типизированный эмиттер событий для мутаций SceneGraph |
-| **Десктоп** | Tauri v2 | ~5 МБ нативное приложение (против ~100 МБ у Electron), бэкенд на Rust |
-| **Сборка** | Vite 7 | Быстрый HMR, нативные ES-модули |
-| **Тестирование** | Playwright + bun:test | Визуальная регрессия (E2E) + быстрые модульные тесты |
-| **Линтинг** | oxlint | На основе Rust, на порядки быстрее ESLint |
-| **Форматирование** | oxfmt | Форматирование на основе Rust |
-| **Проверка типов** | typescript-go (tsgo) | Нативная Go-реализация проверки типов TypeScript |
-
-## Ключевые зависимости
-
-```json
-{
- "canvaskit-wasm": "^0.40.0",
- "vue": "^3.5.29",
- "yoga-layout": "npm:@open-pencil/[email protected]",
- "nanoevents": "^9.1.0",
- "sucrase": "^3.35.1",
- "reka-ui": "^2.8.2",
- "tailwindcss": "^4.2.1",
- "culori": "^4.0.2",
- "fzstd": "^0.1.1",
- "fflate": "^0.8.2",
- "trystero": "^0.20.0",
- "yjs": "^13.6.24",
- "y-indexeddb": "^9.0.12"
-}
-```
-
-## Почему не...
-
-### Почему не SVG-рендеринг?
-
-SVG медленный для сложных документов. Каждый узел — это элемент DOM — 10 000 узлов означают 10 000 DOM-элементов с расходами на макет, отрисовку и композитинг. CanvasKit отрисовывает всё на одну GPU-поверхность. (Penpot по-прежнему использует SVG-рендеринг по умолчанию, но разрабатывает опциональный Rust/Skia WASM рендерер.)
-
-### Почему не Electron (как десктоп Figma)?
-
-Tauri v2 использует системный webview (~5 МБ) вместо включения Chromium (~100 МБ). Бэкенд на Rust обеспечивает нативную производительность для файлового ввода-вывода и системной интеграции.
-
-### Почему не React (как в первоначальном плане)?
-
-Проект мигрировал с React на Vue 3 на ранней стадии разработки. Система реактивности Vue и композаблы VueUse оказались более эргономичными для управления состоянием редактора.
-
-### Почему не собственный движок макетов?
-
-Yoga поддерживается Meta, проверен на миллиардах устройств с React Native и реализует спецификацию CSS flexbox. Создание собственного движка заняло бы месяцы работы для достижения того же уровня корректности.
-
-## Планируемые технологии
-
-| Технология | Назначение | Этап |
-|-----------|---------|-------|
-| CSS Grid в Yoga | Макет на основе сетки | ✅ Включено через [форк Yoga](https://github.com/open-pencil/yoga/tree/grid) (`@open-pencil/yoga-layout`) |
diff --git a/packages/docs/ru/guide/comparison.md b/packages/docs/ru/overview/comparison.md
similarity index 100%
rename from packages/docs/ru/guide/comparison.md
rename to packages/docs/ru/overview/comparison.md
diff --git a/packages/docs/ru/guide/features.md b/packages/docs/ru/overview/features.md
similarity index 100%
rename from packages/docs/ru/guide/features.md
rename to packages/docs/ru/overview/features.md
diff --git a/packages/docs/ru/programmable/index.md b/packages/docs/ru/programmable/index.md
index a27fdd4c6..f5f75e70e 100644
--- a/packages/docs/ru/programmable/index.md
+++ b/packages/docs/ru/programmable/index.md
@@ -12,7 +12,7 @@ OpenPencil работает с дизайн-файлами как с данны
## ИИ-чат
-Встроенный ассистент имеет доступ к 87 инструментам, покрывающим все возможности редактора. Опишите, что вам нужно, на естественном языке — «добавь тень 16px ко всем кнопкам», «создай компонент карточки с вариантом для тёмной темы», «экспортируй каждый фрейм на этой странице в 2×».
+Встроенный ассистент имеет доступ к более чем 90 инструментам, покрывающим все возможности редактора. Опишите, что вам нужно, на естественном языке — «добавь тень 16px ко всем кнопкам», «создай компонент карточки с вариантом для тёмной темы», «экспортируй каждый фрейм на этой странице в 2×».
[ИИ-чат →](./ai-chat)
diff --git a/packages/docs/ru/guide/figma-comparison.md b/packages/docs/ru/reference/figma-compatibility.md
similarity index 99%
rename from packages/docs/ru/guide/figma-comparison.md
rename to packages/docs/ru/reference/figma-compatibility.md
index 27878adfe..6f2bb9602 100644
--- a/packages/docs/ru/guide/figma-comparison.md
+++ b/packages/docs/ru/reference/figma-compatibility.md
@@ -218,7 +218,7 @@
| Сниппеты кода | 🟡 | Экспорт JSX с подсветкой синтаксиса и копированием; нет сниппетов CSS/Swift/Kotlin |
| Экспорт Tailwind CSS v4 | ✅ | Экспорт как HTML с утилитарными классами Tailwind из панели Code, CLI или программно |
| Figma for VS Code | 🔲 | Интеграция с редактором кода |
-| MCP-сервер | ✅ | @open-pencil/mcp с транспортами stdio + HTTP; 87 основных + 3 файловых = 90 инструментов |
+| MCP-сервер | ✅ | @open-pencil/mcp с транспортами stdio + HTTP; более 90 инструментов, включая файловые операции |
| CLI-инструменты | ✅ | Headless CLI: info, tree, find, export, analyze, node, pages, variables, eval; MCP-сервер со stdio + HTTP |
## Figma Draw
diff --git a/tools/docs/package.json b/tools/docs/package.json
new file mode 100644
index 000000000..039bd8190
--- /dev/null
+++ b/tools/docs/package.json
@@ -0,0 +1,8 @@
+{
+ "name": "@open-pencil/docs-tools",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "test": "bun test tests"
+ }
+}
diff --git a/tools/docs/src/check.ts b/tools/docs/src/check.ts
new file mode 100644
index 000000000..0bc3712a7
--- /dev/null
+++ b/tools/docs/src/check.ts
@@ -0,0 +1,98 @@
+#!/usr/bin/env bun
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+ DE,
+ DE_PROG,
+ EN,
+ EN_PROG,
+ ES,
+ ES_PROG,
+ FR,
+ FR_PROG,
+ IT,
+ IT_PROG,
+ PL,
+ PL_PROG,
+ RU,
+ RU_PROG
+} from '#docs-config/labels'
+import type { ProgrammableLabels, SidebarLabels } from '#docs-config/labels'
+import { sdkSidebar } from '#docs-config/sdk-sidebar'
+import {
+ developmentSidebar,
+ guideSidebar,
+ programmableSidebar,
+ referenceSidebar,
+ userGuideSidebar
+} from '#docs-config/sidebars'
+
+import { checkDocsIntegrity } from './integrity'
+
+interface SidebarItem {
+ items?: SidebarItem[]
+ link?: string
+}
+
+interface LocaleConfig {
+ labels: SidebarLabels
+ prefix: string
+ programmable: ProgrammableLabels
+}
+
+const localeConfigs: LocaleConfig[] = [
+ { labels: EN, prefix: '', programmable: EN_PROG },
+ { labels: DE, prefix: '/de', programmable: DE_PROG },
+ { labels: ES, prefix: '/es', programmable: ES_PROG },
+ { labels: FR, prefix: '/fr', programmable: FR_PROG },
+ { labels: IT, prefix: '/it', programmable: IT_PROG },
+ { labels: PL, prefix: '/pl', programmable: PL_PROG },
+ { labels: RU, prefix: '/ru', programmable: RU_PROG }
+]
+
+function sidebarLinks(items: SidebarItem[]): string[] {
+ return items.flatMap((item) => [
+ ...(item.link ? [item.link] : []),
+ ...(item.items ? sidebarLinks(item.items) : [])
+ ])
+}
+
+function localeSidebarLinks({ labels, prefix, programmable }: LocaleConfig): string[] {
+ const developmentPrefix = prefix ? '' : prefix
+ return sidebarLinks([
+ ...guideSidebar(prefix, labels),
+ ...userGuideSidebar(prefix, labels),
+ ...programmableSidebar(prefix, programmable),
+ ...sdkSidebar(prefix),
+ ...referenceSidebar(prefix, 'Reference', labels),
+ ...developmentSidebar(developmentPrefix, 'Development', labels)
+ ])
+}
+
+const repoRoot = fileURLToPath(new URL('../../..', import.meta.url))
+const docsRoot = resolve(repoRoot, 'packages/docs')
+const result = checkDocsIntegrity({
+ docsRoot,
+ localePrefixes: localeConfigs.slice(1).map(({ prefix }) => prefix.slice(1)),
+ redirectsPath: resolve(docsRoot, 'public/_redirects'),
+ sidebarLinks: localeConfigs.flatMap(localeSidebarLinks)
+})
+
+const missingCounts = Object.values(result.localeMissingPages).map((pages) => pages.length)
+const translationCounts = missingCounts.map(
+ (missing) => result.canonicalPageCount - missing
+)
+console.log(
+ `Translation coverage: ${Math.min(...translationCounts)}–${Math.max(...translationCounts)} of ${result.canonicalPageCount} canonical pages per locale.`
+)
+
+if (result.errors.length > 0) {
+ console.error('\nDocumentation integrity check failed:')
+ for (const error of result.errors) console.error(`- ${error}`)
+ process.exit(1)
+}
+
+console.log(
+ `Documentation integrity check passed for ${result.markdownFiles.length} Markdown files.`
+)
diff --git a/tools/docs/src/integrity.ts b/tools/docs/src/integrity.ts
new file mode 100644
index 000000000..4d35279c2
--- /dev/null
+++ b/tools/docs/src/integrity.ts
@@ -0,0 +1,179 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, extname, join, normalize, relative, resolve, sep } from 'node:path'
+
+import { parse as parseCloudflareRedirects } from 'cloudflare-redirect-parser'
+import type { Definition, Link, Root } from 'mdast'
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { visit } from 'unist-util-visit'
+
+export interface DocsIntegrityOptions {
+ docsRoot: string
+ localePrefixes: readonly string[]
+ redirectsPath: string
+ sidebarLinks: readonly string[]
+}
+
+export interface DocsIntegrityResult {
+ canonicalPageCount: number
+ errors: string[]
+ localeMissingPages: Record<string, string[]>
+ markdownFiles: string[]
+}
+
+const EXTERNAL_SCHEMES = /^(?:[a-z][a-z\d+.-]*:|\/\/)/i
+const MEDIA_EXTENSIONS = new Set([
+ '.avif',
+ '.fig',
+ '.gif',
+ '.ico',
+ '.jpeg',
+ '.jpg',
+ '.json',
+ '.pen',
+ '.png',
+ '.svg',
+ '.txt',
+ '.webp'
+])
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308])
+
+function walkMarkdown(directory: string): string[] {
+ if (!existsSync(directory)) return []
+
+ return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+ const path = join(directory, entry.name)
+ if (entry.name === 'node_modules' || entry.name === '.vitepress') return []
+ if (entry.isDirectory()) return walkMarkdown(path)
+ return entry.isFile() && entry.name.endsWith('.md') ? [path] : []
+ })
+}
+
+function routeCandidates(docsRoot: string, route: string): string[] {
+ const routePath = route.replace(/^\//, '').replace(/\/$/, '')
+ const base = resolve(docsRoot, routePath)
+ if (extname(base)) return [base]
+ return [base, `${base}.md`, join(base, 'index.md')]
+}
+
+function fileCandidates(path: string): string[] {
+ if (extname(path)) return [path]
+ return [path, `${path}.md`, join(path, 'index.md')]
+}
+
+function routeExists(docsRoot: string, route: string): boolean {
+ return routeCandidates(docsRoot, route).some(existsSync)
+}
+
+function markdownLinks(source: string): Array<Link | Definition> {
+ const links: Array<Link | Definition> = []
+ const tree = fromMarkdown(source) as Root
+ visit(tree, 'link', (node) => links.push(node))
+ visit(tree, 'definition', (node) => links.push(node))
+ return links
+}
+
+function validateMarkdownLinks(docsRoot: string, markdownFiles: string[]): string[] {
+ const errors: string[] = []
+
+ for (const file of markdownFiles) {
+ for (const link of markdownLinks(readFileSync(file, 'utf8'))) {
+ const target = link.url.split(/[?#]/, 1)[0]?.trim() ?? ''
+ if (!target || target.startsWith('#') || EXTERNAL_SCHEMES.test(target)) continue
+
+ const path = target.startsWith('/')
+ ? resolve(docsRoot, target.replace(/^\//, ''))
+ : resolve(dirname(file), target)
+ if (MEDIA_EXTENSIONS.has(extname(path)) || fileCandidates(path).some(existsSync)) continue
+
+ errors.push(`${relative(docsRoot, file)} links to missing target '${target}'.`)
+ }
+ }
+
+ return errors
+}
+
+function validateRedirects(docsRoot: string, redirectsPath: string): string[] {
+ if (!existsSync(redirectsPath)) return [`Missing redirects file '${redirectsPath}'.`]
+
+ const errors: string[] = []
+ const source = readFileSync(redirectsPath, 'utf8')
+ const redirects = parseCloudflareRedirects(source)
+ const seenSources = new Set<string>()
+
+ for (const redirect of redirects) {
+ const status = redirect.status ?? 302
+ if (seenSources.has(redirect.from)) {
+ errors.push(`Redirect '${redirect.from}' is duplicated.`)
+ }
+ seenSources.add(redirect.from)
+
+ if (!REDIRECT_STATUSES.has(status)) {
+ errors.push(`Redirect '${redirect.from}' has unsupported status '${status}'.`)
+ }
+ if (!redirect.from.startsWith('/') || !redirect.to.startsWith('/')) {
+ errors.push(`Redirect '${redirect.from}' must use root-relative paths.`)
+ continue
+ }
+ if (routeExists(docsRoot, redirect.from)) {
+ errors.push(`Redirect source '${redirect.from}' still has a page and would shadow it.`)
+ }
+ if (!routeExists(docsRoot, redirect.to)) {
+ errors.push(`Redirect '${redirect.from}' targets missing page '${redirect.to}'.`)
+ }
+ }
+
+ return errors
+}
+
+function canonicalMarkdownPaths(
+ docsRoot: string,
+ localePrefixes: readonly string[],
+ markdownFiles: string[]
+): string[] {
+ const localeDirectories = new Set(localePrefixes)
+ return markdownFiles
+ .map((file) => relative(docsRoot, file))
+ .filter((path) => !localeDirectories.has(path.split(sep)[0] ?? ''))
+ .sort()
+}
+
+function localeMissingPages(
+ docsRoot: string,
+ localePrefixes: readonly string[],
+ canonicalPaths: string[]
+): Record<string, string[]> {
+ return Object.fromEntries(
+ localePrefixes.map((locale) => [
+ locale,
+ canonicalPaths.filter((path) => !existsSync(join(docsRoot, locale, path)))
+ ])
+ )
+}
+
+function validateSidebarLinks(docsRoot: string, sidebarLinks: readonly string[]): string[] {
+ const errors: string[] = []
+ for (const link of new Set(sidebarLinks)) {
+ if (!link.startsWith('/') || EXTERNAL_SCHEMES.test(link) || routeExists(docsRoot, link))
+ continue
+ errors.push(`Sidebar links to missing page '${link}'.`)
+ }
+ return errors
+}
+
+export function checkDocsIntegrity(options: DocsIntegrityOptions): DocsIntegrityResult {
+ const docsRoot = normalize(options.docsRoot)
+ const markdownFiles = walkMarkdown(docsRoot)
+ const canonicalPaths = canonicalMarkdownPaths(docsRoot, options.localePrefixes, markdownFiles)
+ const errors = [
+ ...validateMarkdownLinks(docsRoot, markdownFiles),
+ ...validateSidebarLinks(docsRoot, options.sidebarLinks),
+ ...validateRedirects(docsRoot, options.redirectsPath)
+ ].sort()
+
+ return {
+ canonicalPageCount: canonicalPaths.length,
+ errors,
+ localeMissingPages: localeMissingPages(docsRoot, options.localePrefixes, canonicalPaths),
+ markdownFiles
+ }
+}
diff --git a/tools/docs/tests/integrity.test.ts b/tools/docs/tests/integrity.test.ts
new file mode 100644
index 000000000..e0638549d
--- /dev/null
+++ b/tools/docs/tests/integrity.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, test } from 'bun:test'
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { checkDocsIntegrity } from '../src/integrity'
+
+async function fixture() {
+ const docsRoot = await mkdtemp(join(tmpdir(), 'open-pencil-docs-integrity-'))
+ await mkdir(join(docsRoot, 'public'), { recursive: true })
+ return docsRoot
+}
+
+async function write(path: string, content = '# Page') {
+ await mkdir(join(path, '..'), { recursive: true })
+ await writeFile(path, content, 'utf8')
+}
+
+function check(docsRoot: string, sidebarLinks: string[] = []) {
+ return checkDocsIntegrity({
+ docsRoot,
+ localePrefixes: ['ru'],
+ redirectsPath: join(docsRoot, 'public/_redirects'),
+ sidebarLinks
+ })
+}
+
+describe('checkDocsIntegrity', () => {
+ test('accepts valid Markdown, sidebars, redirects, and incomplete locales', async () => {
+ const docsRoot = await fixture()
+ await write(join(docsRoot, 'index.md'), '[Page](/page)')
+ await write(join(docsRoot, 'page.md'))
+ await write(join(docsRoot, 'ru/index.md'))
+ await write(join(docsRoot, 'legacy.md'))
+ await writeFile(join(docsRoot, 'public/_redirects'), '/old /page 301\n', 'utf8')
+
+ const result = check(docsRoot, ['/page'])
+
+ expect(result.errors).toEqual([])
+ expect(result.localeMissingPages.ru).toEqual(['legacy.md', 'page.md'])
+ })
+
+ test('uses Markdown syntax instead of treating code parentheses as links', async () => {
+ const docsRoot = await fixture()
+ const markdown = [
+ '`call(not-a-link)`',
+ '',
+ '```ts',
+ 'call(still-not-a-link)',
+ '```',
+ '',
+ '[Page][page]',
+ '',
+ '[page]: /page'
+ ].join('\n')
+ await write(join(docsRoot, 'index.md'), markdown)
+ await write(join(docsRoot, 'page.md'))
+ await writeFile(join(docsRoot, 'public/_redirects'), '/old /page 301\n', 'utf8')
+
+ expect(check(docsRoot).errors).toEqual([])
+ })
+
+ test('reports missing Markdown and sidebar targets', async () => {
+ const docsRoot = await fixture()
+ await write(join(docsRoot, 'index.md'), '[Missing](./missing)')
+ await writeFile(join(docsRoot, 'public/_redirects'), '', 'utf8')
+
+ expect(check(docsRoot, ['/also-missing']).errors).toEqual([
+ "Sidebar links to missing page '/also-missing'.",
+ "index.md links to missing target './missing'."
+ ])
+ })
+
+ test('reports invalid, duplicate, shadowing, and missing redirect targets', async () => {
+ const docsRoot = await fixture()
+ await write(join(docsRoot, 'old.md'))
+ await write(join(docsRoot, 'index.md'))
+ await writeFile(
+ join(docsRoot, 'public/_redirects'),
+ ['/old /missing 301', '/old / 302', '/bad / 999'].join('\n'),
+ 'utf8'
+ )
+
+ expect(check(docsRoot).errors).toEqual([
+ "Redirect '/bad' has unsupported status '999'.",
+ "Redirect '/old' is duplicated.",
+ "Redirect '/old' targets missing page '/missing'.",
+ "Redirect source '/old' still has a page and would shadow it.",
+ "Redirect source '/old' still has a page and would shadow it."
+ ])
+ })
+})
diff --git a/tools/docs/tsconfig.json b/tools/docs/tsconfig.json
new file mode 100644
index 000000000..1018f7941
--- /dev/null
+++ b/tools/docs/tsconfig.json
@@ -0,0 +1,10 @@
+{
+ "extends": "../../tsconfig.json",
+ "compilerOptions": {
+ "baseUrl": "../..",
+ "paths": {
+ "#docs-config/*": ["packages/docs/.vitepress/*"]
+ }
+ },
+ "include": ["src/**/*.ts"]
+}
diff --git a/tsconfig.json b/tsconfig.json
index 4635885c0..b99713584 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -43,6 +43,9 @@
"#tests/*": [
"./tests/*"
],
+ "#docs-config/*": [
+ "./packages/docs/.vitepress/*"
+ ],
"tinykeys": [
"./node_modules/tinykeys/dist/tinykeys.d.ts"
],