perf(packages/core): incremental sync engine — only process what changed

.changeset/incremental-sync-engine.md

@@ -0,0 +1,15 @@
+---
+'@zpress/core': minor
+'@zpress/cli': minor
+---
+
+Sync engine now only processes what changed instead of running a full sync on every pass.
+
+- **mtime-based page skip**: pages whose source mtime and frontmatter hash match the previous manifest skip the entire read/transform/hash pipeline
+- **Parallel page copy**: all pages are copied concurrently via `Promise.all` instead of sequential reduce
+- **Parallel `copyAll`**: public asset directory copy runs in parallel
+- **Asset generation skip**: banner/logo/icon SVGs skip generation entirely when the asset config hash is unchanged; `shouldGenerate` also compares content to avoid redundant writes
+- **Image copy skip**: destination images are skipped when their mtime is at least as recent as the source
+- **OpenAPI spec caching**: specs are only re-parsed when their file mtime changes; a shared cache persists across dev-mode sync passes and is cleared on config reload
+- **Structural change detection**: `resolvedCount` mismatch between syncs forces a full resync to handle added/removed pages correctly
+- **Build system migration**: switched CLI from rslib to kidd's native build system (tsdown-based), with static command imports, proper dependency externalization, and React/Ink TUI dev screen

CONTRIBUTING.md

@@ -65,7 +65,7 @@ Write clear, concise descriptions in the imperative mood ("add feature" not "add
 
 ## Project Structure
 
-```
+```text
 packages/
 ├── cli/              # @zpress/cli — CLI commands, watcher, Rspress integration
 ├── core/             # @zpress/core — config loading, sync engine, sidebar/nav generation

contributing/README.md

@@ -6,6 +6,7 @@ Welcome to the zpress contributing docs. This directory contains standards, temp
 
 - **Standards** define the rules -- read the relevant standard before writing code or docs.
 - **Concepts** explain the "what" and "why" behind key architectural decisions.
+- **References** are lookup tables for commands, flags, and APIs.
 - **Guides** are step-by-step walkthroughs for common tasks.
 
 ## Table of Contents
@@ -38,10 +39,20 @@ Welcome to the zpress contributing docs. This directory contains standards, temp
 
 ### Concepts
 
-- [Architecture](./concepts/architecture.md) -- Package ecosystem, sync engine, UI theme, data flow
-- [CLI](./concepts/cli.md) -- Commands, dev server, file watching, build pipeline
+- [Architecture](./concepts/architecture.md) -- Package ecosystem, layers, design decisions, data flow
+- [Config](./concepts/config.md) -- Config system, output structure, Rspress integration
+- [Engine](./concepts/engine/overview.md) -- Sync engine overview, build vs dev, key concepts
+  - [Pipeline](./concepts/engine/pipeline.md) -- Sync pipeline, page transformation, entry resolution
+  - [Incremental Sync](./concepts/engine/incremental.md) -- Mtime skipping, content hashing, structural change detection
+  - [OpenAPI Sync](./concepts/engine/openapi.md) -- Spec dereferencing, MDX generation, caching
+  - [Dev Mode](./concepts/engine/dev.md) -- File watching, debouncing, HMR, config reload
+
+### References
+
+- [CLI](./references/cli.md) -- Command syntax, flags, Rspress integration
 
 ### Guides
 
 - [Getting Started](./guides/getting-started.md) -- Local setup, reading order, Claude Code configuration
 - [Developing a Feature](./guides/developing-a-feature.md) -- Branch, code, test, changeset, PR, merge
+- [Publishing VS Code Extension](./guides/publishing-vscode-extension.md) -- Package and publish the zpress VS Code extension

contributing/concepts/config.md

@@ -0,0 +1,84 @@
+# Config
+
+The single source of truth for the entire documentation site.
+
+## Overview
+
+The config file (`zpress.config.ts`) defines the information architecture -- content structure, navigation, metadata, and workspaces. It is loaded via [c12](https://github.com/unjs/c12) and validated at runtime by `loadConfig()`. Validation errors are returned as `Result` tuples; the CLI layer handles reporting and exits.
+
+## Supported Formats
+
+| Format     | Files                                           |
+| ---------- | ----------------------------------------------- |
+| TypeScript | `zpress.config.ts`, `.mts`, `.cts`              |
+| JavaScript | `zpress.config.js`, `.mjs`, `.cjs`              |
+| Data       | `zpress.config.json`, `.jsonc`, `.yml`, `.yaml` |
+
+## Shape
+
+```ts
+import { defineConfig } from '@zpress/kit'
+
+export default defineConfig({
+  title: 'My Docs',
+  description: 'Platform documentation',
+  tagline: 'A short tagline for the hero section',
+  sections: [
+    /* entry tree */
+  ],
+  apps: [
+    /* workspace items */
+  ],
+  packages: [
+    /* workspace items */
+  ],
+  nav: 'auto',
+})
+```
+
+| Field         | Purpose                                           |
+| ------------- | ------------------------------------------------- |
+| `title`       | Site title, used in hero and metadata             |
+| `description` | Site description for SEO                          |
+| `tagline`     | Hero section subtitle                             |
+| `sections`    | Entry tree defining the information architecture  |
+| `apps`        | Workspace items for application docs              |
+| `packages`    | Workspace items for shared package docs           |
+| `workspaces`  | Custom workspace groups                           |
+| `nav`         | Top-level navigation (`'auto'` or explicit array) |
+
+## Output Structure
+
+The sync engine writes everything to `.zpress/`:
+
+```tree
+.zpress/
+├── content/                 # Synced markdown + generated MDX (Rspress root)
+│   ├── index.md             # Home page (auto-generated or from source)
+│   ├── getting-started.md
+│   ├── guides/
+│   └── .generated/          # Machine-generated metadata
+│       ├── sidebar.json     # Multi-sidebar config
+│       ├── nav.json         # Top-level navigation
+│       └── workspaces.json  # Workspace data for home page
+├── public/                  # Static assets (logos, icons, banners)
+├── dist/                    # Build output (HTML, CSS, JS)
+└── cache/                   # Rspress build cache
+```
+
+Rspress's root is set to `.zpress/content/`. It never sees the original repo layout.
+
+## Rspress Integration
+
+`createRspressConfig()` in `@zpress/ui` bridges sync output to Rspress:
+
+- Sets Rspress `root` to `.zpress/content/`
+- Reads generated `sidebar.json`, `nav.json`, `workspaces.json` from `.generated/`
+- Registers the zpress plugin (theme provider, edit-source button, mermaid, file trees)
+- Configures Rsbuild aliases so generated MDX can import `@zpress/ui/theme` components
+
+## References
+
+- [Architecture](./architecture.md)
+- [Engine](./engine/overview.md)
+- [CLI Reference](../references/cli.md)