@hutusi/amytis 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.16.0] - 2026-06-01
+
+### Added
+- **VuePress Book Pipeline**: Books are now first-class with nested chapter ids and TOCs, a catch-all chapter route, collapsible sections in the chapter sidebar, book-level LaTeX/math, VuePress `:::container` admonitions, and inter-chapter links. Includes a new `bun run sync-vuepress-book` importer that handles frontmatter-less chapters and stale `.md` references gracefully.
+- **Shiki Syntax Highlighting**: Replaced `react-syntax-highlighter`/Prism with a build-time Shiki pipeline across both Markdown/MDX and rST. Unknown fence languages now degrade to plaintext with a build-log warning instead of crashing the build, and any bundled Shiki language is lazy-loaded on demand.
+- **Code-Group Tabs**: New `:::code-group` (Markdown) and `.. code-group::` (rST) directives render fenced blocks as switchable tabs, with auto-detected icons for languages, package managers, and config files.
+- **Shiki Notation Comments**: Inline `// [!code focus]`, `[!code error]`, `[!code warning]`, `[!code highlight]`, and diff markers render with visual indicators inside code blocks.
+- **GitHub-Flavored Alert Blockquotes**: `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]` render as styled callouts in both Markdown and rST (admonition visual parity).
+- **Reading Meta**: Word count appears alongside reading time on post and chapter headers, with Chinese localization (`5 分钟阅读`).
+- **External Link Affordance**: Outward-arrow icon on external links, opened in a new tab.
+- **Code Block Polish**: Real tab icons via Iconify for code-group headers, proper-case language labels, a more prominent highlighted-line background, and rST `:linenos:` / `:emphasize-lines:` / `:caption:` support.
+
+### Changed
+- **Mermaid Diagrams** now render frameless by default — no outer border, padding, background, or shadow. Diagram SVGs use the full column width.
+- **`showChapterExcerpt`** defaults to `false` on books; opt back in per-book.
+- **Markdown Rendering Fidelity**: Single-line `$$ x $$` block math now expands and parses as display math; block math centers via `.katex-display`; VuePress inline `<img>` styling is preserved through import; KaTeX `unicodeTextInMathMode` warnings (noise on CJK math labels) are scoped-silenced.
+- **Dependency Refresh**: TypeScript 5.9 → 6.0, ESLint 9 → 10 (config rewritten without `eslint-config-next`), Next.js + safe minor/patch sweep, `@types/node` 24 → 25, `pdf-to-img` 5 → 6.
+
+### Fixed
+- **Hydration Mismatches**: Locale-bound text in `TocPanel`, `PostNavigation`, `PostSidebar`, and `ShareBar` no longer logs a hydration error on first paint for users whose stored locale differs from `siteConfig.i18n.defaultLocale`. Mermaid's mutation-prone wrapper is likewise marked.
+- **Table Padding**: Restored horizontal padding on prose table cells (the earlier `:where()`-based override was silently stripped by Tailwind v4 / Lightning CSS; replaced with a plain descendant selector that survives compilation).
+- **rST Fallback Parser**: Added rendering for `.. figure::`, line blocks, admonitions (including custom `.. cnote::` with caption), `:doc:` / `:ref:` / `:numref:` roles; suppresses `.. toctree::` from rendered body; normalizes escaped whitespace in inline rST.
+- **React 19 Warnings**: Resolved `react-hooks/set-state-in-effect` warnings and silenced image-preload warnings for local images. Eager `CoverImage` variants are no longer deprioritized.
+- **Copy-Paste UX**: Stripped per-paragraph backgrounds on article copy to prevent "striping" when pasting into rich-text editors. Clipboard-API guard before `preventDefault`.
+- **Misc**: `<summary>` styled as an interactive link; code-group icon lookups via `Object.hasOwn`; shiki dedup state reset in `finally`; `<style>` element scoping for shiki output; book import edge cases (URI decode, Vue component warnings, fenced blocks in container normalizer, chapter image paths relative to parent dir).
+
 ## [1.15.0] - 2026-04-12
 
 ### Added

package/CLAUDE.md

@@ -1,231 +1,102 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Guidance for Claude Code in this repo. Rules, gotchas, and pointers — not reference material.
 
-## Project Overview
+## Project
 
-Amytis is a static "digital garden" blog built with Next.js 15+ (App Router), React 19, and Tailwind CSS v4. Content is authored in MDX/Markdown files and statically generated at build time. Features include series support, multi-language (i18n), configurable themes, and comments integration.
+Amytis: static digital-garden blog (Next.js 16 App Router, React 19, Tailwind v4, static export). Content in MDX / Markdown (primary), rST (legacy support); everything resolves at build time. Package manager: bun.
 
-## Commands
+## Essential commands
 
 ```bash
-# Development
-bun dev                    # Start dev server at localhost:3000
-bun run lint               # Run ESLint
-
-# Testing
-bun test                   # Run all tests
-bun run test:unit          # Run unit tests (src/)
-bun run test:int           # Run integration tests
-bun run test:e2e           # Run end-to-end tests
-bun run test:mobile        # Run Playwright mobile compatibility tests (requires dev server)
-bun test path/to/file.test.ts  # Run a single test file
-
-# Build
-bun run build              # Full production build (copies assets, builds Next.js, optimizes images)
-bun run build:dev          # Development build (no image optimization, faster) — also regenerates Pagefind search index in public/pagefind/
-bun run clean              # Remove .next, out, public/posts directories
-
-# Deploy
-bun run deploy             # Deploy out/ to Linux/nginx server via rsync+sshpass (reads .env.local)
-
-# Content creation
-bun run new "Post Title"              # Create new post
-bun run new-series "Series Name"      # Create new series
-bun run new-from-pdf doc.pdf          # Create post from PDF
-bun run new-from-images ./photos      # Create post from image folder
-bun run new-flow                      # Create today's flow note
-bun run add-series-redirects                    # Add redirectFrom to all series posts (for autoPaths migration)
-bun run add-series-redirects <series-slug>      # Add redirectFrom to one series only
-bun run add-series-redirects --dry-run          # Preview without writing
-bun run new-flow-from-chat            # Import all new files from imports/chats/
-bun run sync-book                     # Sync chapters list for all books from disk
-bun run sync-book <slug>              # Sync chapters list for one book
+bun dev                 # dev server (Turbopack, http://localhost:3000)
+bun run lint            # ESLint
+bun test                # all tests
+bun run build           # production build (image optimization + Pagefind)
+bun run build:dev       # faster build; regenerates public/pagefind/ for search-in-dev
+bun run clean           # nuke .next, out, public/posts when caches misbehave
 ```
 
-## Design Principles
-
-- **Strict build over silent runtime failure.** This is a statically exported site — all misconfiguration must be caught at build time. Prefer `throw` in `generateStaticParams` and similar build-time functions over silent skips or `console.warn`. Examples: `validateSeriesAutoPaths` throws on slug collisions; `redirectFrom` alias conflicts should throw rather than silently producing broken redirects.
-
-## Architecture
-
-### Data Flow
-
-1. **Content source**: MDX/Markdown files in `content/posts/` and `content/series/`
-2. **Data layer**: `src/lib/markdown.ts` - reads files with Node `fs`, parses frontmatter with `gray-matter`, validates with Zod
-3. **Static generation**: Routes use `generateStaticParams` to pre-render at build time
-4. **Rendering**: `react-markdown` with remark/rehype plugins for GFM, math (KaTeX), syntax highlighting, and Mermaid diagrams
-
-### Key Files
-
-- `site.config.ts` - Site configuration (nav, social, pagination, themes, i18n, analytics, comments)
-- `src/lib/markdown.ts` - Data access layer with all content query functions
-- `src/lib/urls.ts` - Central URL helpers (`getPostUrl`, `getPostsBasePath`, `getSeriesCustomPaths`, etc.) — always use these instead of hardcoding `/posts/[slug]`
-- `src/lib/search-utils.ts` - Pure search utilities (URL type detection, date extraction, title cleaning, markdown stripping) shared by `Search` and the search index route
-- `src/app/globals.css` - Theme CSS variables and color palettes
-- `src/components/MarkdownRenderer.tsx` - MDX rendering with all plugins
-- `src/i18n/translations.ts` - Language strings for i18n
-
-### Route Structure
-
-- `/` - Homepage with hero, featured series, featured posts, latest writing
-- `/posts/[slug]` - Individual post pages
-- `/posts/page/[page]` - Paginated post listing
-- `/series` - All series overview
-- `/series/[slug]` - Single series with its posts
-- `/series/[slug]/page/[page]` - Series pagination
-- `/tags` - Tag cloud with post counts
-- `/tags/[tag]` - Posts filtered by tag
-- `/authors/[author]` - Posts filtered by author
-- `/archive` - Chronological listing grouped by year/month
-- `/books` - All books overview
-- `/books/[slug]` - Single book with chapter listing
-- `/books/[slug]/[chapter]` - Individual chapter page
-- `/flows` - Flow notes listing (paginated)
-- `/flows/page/[page]` - Paginated flow listing
-- `/flows/[year]` - Flows filtered by year
-- `/flows/[year]/[month]` - Flows filtered by month
-- `/flows/[year]/[month]/[day]` - Single flow detail page
-- `/[slug]` - Static pages (about, subscribe, etc.) and custom posts/series listing pages
-- `/[prefix]/[slug]` - Posts at custom URL prefixes (e.g. `/articles/my-post`, `/weeklies/my-post`)
-- `/[prefix]/page/[page]` - Paginated listing at custom URL prefixes
-
-### Content Structure
-
-**Posts** support two formats:
-- **Flat file**: `content/posts/my-post.mdx`
-- **Nested folder**: `content/posts/my-post/index.mdx` (allows co-located images in `./images/`)
-
-**Series** live in `content/series/[slug]/index.mdx` with optional `images/` folder for cover images.
-
-**Books** live in `content/books/[slug]/` with `index.mdx` for metadata and separate `.mdx` files per chapter. The `index.mdx` frontmatter defines chapter ordering with an optional parts structure.
-
-**Flows** (daily notes) live in `content/flows/YYYY/MM/DD.md` (or `.mdx`). Each flow has a date, title, excerpt, tags, and markdown content.
-
-Date-prefixed filenames (`2026-01-01-my-post.mdx`) extract dates automatically.
-
-## Config Files
-
-There are two config files that must be kept in sync:
-
-- **`site.config.ts`** — the live config for this repo (i18n enabled; locale-aware fields use `{ en: '...', zh: '...' }` objects)
-- **`site.config.example.ts`** — single-language starter template shipped via `create-amytis`; locale-aware fields use plain strings; optional features (books, flow) default to disabled
-
-**Rule:** Any schema change to `site.config.ts` (new field, renamed field, type change) must be mirrored in `site.config.example.ts`. Locale-aware values (`string | Record<string, string>`) should use plain strings in the example.
-
-## Configuration (`site.config.ts`)
-
-Key configuration options:
-- `nav` - Navigation links with weights
-- `social` - GitHub, Twitter, email links for footer
-- `series.navbar` - Series slugs to show in navbar dropdown
-- `series.customPaths` - Per-series custom URL prefix e.g. `{ 'weeklies': 'weeklies' }` → posts at `/weeklies/[slug]`
-- `pagination.posts`, `pagination.series` - Items per page
-- `themeColor` - 'default' | 'blue' | 'rose' | 'amber'
-- `hero` - Homepage hero title and subtitle
-- `i18n` - Default locale and supported locales
-- `featured.series` - Scrollable series: `scrollThreshold` (default: 2), `maxItems` (default: 6)
-- `featured.stories` - Scrollable stories: `scrollThreshold` (default: 1), `maxItems` (default: 5)
-- `analytics.providers` - array of enabled providers: `['umami', 'google']`; `[]` disables analytics
-- `comments.provider` - 'giscus' | 'disqus' | null
-- `feed.format` - 'rss' | 'atom' | 'both'
-- `feed.content` - 'full' | 'excerpt'
-- `feed.maxItems` - max feed items (0 = unlimited)
-- `footer.bottomLinks` - custom links in the footer bottom bar (ICP, cookie policy, etc.); `text` accepts plain string or `{ en, zh }` locale map
-- `posts.basePath` - Custom URL prefix for all posts (default: `'posts'`); e.g. `'articles'` → posts at `/articles/[slug]`
-- `posts.authors.default` - Fallback authors when a post has none set in frontmatter
-- `posts.authors.showInHeader` - Show author byline below post title (default: true)
-- `posts.authors.showAuthorCard` - Show author card at end of post (default: true)
-- `posts.excludeFromListing` - Series slugs whose posts are hidden from `/posts` listing pages
-- `authors` - Per-author profiles: `bio`, `avatar` (image path), `social` (array of `{ image, description }`)
-
-## Content Frontmatter
-
-### Posts
-
-```yaml
----
-title: "Post Title"
-subtitle: "Optional subtitle line"  # Rendered below the title in italic
-date: "2026-01-01"
-excerpt: "Optional summary (auto-generated if omitted)"
-category: "Category Name"
-tags: ["tag1", "tag2"]
-authors: ["Author Name"]
-series: "series-slug"      # Link to a series
-draft: true                # Hidden in production
-featured: true             # Show in featured section
-pinned: true               # Always shown in featured section; never shuffled away (hero = most recent pinned)
-coverImage: "./images/cover.jpg"  # Local or external URL
-latex: true                # Enable KaTeX math
-toc: false                 # Hide table of contents
-layout: "simple"           # Use simple layout (default: "post")
-externalLinks:             # Links to external discussions
-  - name: "Hacker News"
-    url: "https://news.ycombinator.com/item?id=12345"
-  - name: "V2EX"
-    url: "https://v2ex.com/t/123456"
-redirectFrom:              # Old URLs that should redirect to this post (prefix changes only)
-  - /posts/my-old-slug
-  - /old-series/my-old-slug
----
-```
+Content-creation scripts, test layout, validate pipeline → `docs/CONTRIBUTING.md`.
 
-### Series (`content/series/[slug]/index.mdx`)
-
-```yaml
----
-title: "Series Title"
-excerpt: "Series description"
-date: "2026-01-01"
-coverImage: "./images/cover.jpg"
-featured: true             # Show in featured series
-draft: true                # Hidden in production (default: false)
-sort: "date-asc"           # 'date-asc' | 'date-desc' | 'manual'
-posts: ["post-1", "post-2"] # Manual post ordering (optional)
----
-```
+## Architecture map
 
-### Books (`content/books/[slug]/index.mdx`)
-
-```yaml
----
-title: "Book Title"
-excerpt: "Book description"
-date: "2026-01-01"
-coverImage: "text:DG"           # Cover image or text placeholder
-featured: true                  # Show in featured books
-draft: false
-authors: ["Author Name"]
-chapters:
-  - part: "Part I: Getting Started"    # Optional part grouping
-    chapters:
-      - title: "Chapter Title"
-        id: "chapter-file"             # Maps to chapter-file.mdx or chapter-file/index.mdx
-  - part: "Part II: Advanced"
-    chapters:
-      - title: "Another Chapter"
-        id: "another-chapter"
----
-```
+Quick "where do routes live" lookup. Full reference: `docs/ARCHITECTURE.md`.
+
+- Standard routes follow folder names under `src/app/`: `/posts`, `/series`, `/tags`, `/notes`, `/books`, `/authors`, `/archive`, `/graph`, `/flows/[year]/[month]/[day]`.
+- **Top-level `[slug]` and `[slug]/[postSlug]`** resolve `redirectFrom` aliases and `series.customPaths` — highest-risk dynamic surface; touch with care.
+- Feeds at `feed.xml` / `feed.atom` / `all.xml` / `all.atom` / `flows/feed.{xml,atom}`; sitemap at `sitemap.ts`; search index at `search.json`.
+- Rendering pipeline lives in `src/lib/`: Shiki (`shiki.ts`, `shiki-rst.ts`), remark/rehype plugins (`remark-github-alerts`, `remark-wikilinks`, `remark-code-group`, `rehype-fence-meta`, `rehype-image-metadata`), redirects (`series-redirects.ts`), feeds/JSON-LD (`feed-utils.ts`, `json-ld.ts`).
+
+## Design principles
+
+- **Strict build over silent runtime failure.** Static export means misconfiguration must fail at build time. Use `throw` in `generateStaticParams` and similar — never silent skips or `console.warn`. Precedent: `validateSeriesAutoPaths` throws on slug collisions; `redirectFrom` alias conflicts (reserved slug or duplicate) should also throw, not produce broken redirects.
+  - **Exception**: fence-language resolution in `src/lib/shiki.ts` deliberately degrades to `plaintext` + a deduped `console.warn` instead of throwing. Authors can't reliably predict Shiki's alias coverage, and "typo" vs "legitimate community alias" are indistinguishable from our side, so production deploys shouldn't fail on a single unhighlighted code block. Real typos still surface via the warn output in local/CI build logs.
+- **Validate author input at build time; keep content portable.** Frontmatter via Zod; slug / redirect conflicts throw. Files on disk stay valid `.md` / `.mdx` / `.rst` — no Amytis-specific syntax that breaks other tools.
+
+## Integration-point rules (always go through X)
+
+- **URLs:** always `getPostUrl()` / `getPostsBasePath()` / `getSeriesCustomPaths()` from `src/lib/urls.ts`. Never hardcode `/posts/[slug]` — posts may live at `/articles/[slug]`, custom prefixes (`series.customPaths`), or under `posts.basePath`.
+- **Content reads:** always via `src/lib/markdown.ts` (`getAllPosts`, `getPostBySlug`, `getSeriesData`, etc.). Frontmatter validation belongs in its Zod schemas, not in route files.
+- **Search utilities:** pure helpers (URL type detection, date extraction, title cleaning, markdown stripping) live in `src/lib/search-utils.ts` and are shared by the `Search` component and the search-index route. Don't duplicate them.
+- **i18n strings:** add to `src/i18n/translations.ts`. Locale-aware config fields are `string | Record<string, string>`; resolve via `resolveLocale()` / `resolveLocaleValue()` from `src/lib/i18n.ts`.
+
+## Config sync
+
+`site.config.ts` (this repo — i18n object form, `{ en, zh }`) and `site.config.example.ts` (shipped via `create-amytis` — plain strings, single-locale, optional features default disabled) must stay in sync. Any schema change to one must be mirrored in the other.
+
+## Gotchas (things Claude will get wrong on first try)
+
+- **`turbopackIgnore` on fs reads.** Any `fs.readFileSync()` path expression must be preceded by `/* turbopackIgnore: true */` (see `src/lib/markdown.ts`, `src/lib/rehype-image-metadata.ts`). Missing it causes incorrect bundling.
+- **No AVIF for `coverImage`.** Upstream bug in `next-image-export-optimizer` emits `.webp` files but a `srcset` pointing at `.avif` → 404 in prod. Use `.jpg` / `.png` / `.webp`. See `docs/TROUBLESHOOTING.md`.
+- **Unicode slugs.** Dynamic route pages call `safeDecodeParam()` and try decoded / raw / NFC / NFD variants — don't shortcut with bare `decodeURIComponent()` (it throws on malformed input). When touching dynamic routes, verify both ASCII and Unicode slugs.
+- **`generateStaticParams` returns raw values.** Don't `encodeURIComponent` route params; Next.js handles encoding. Don't link to placeholder routes like `/posts/[slug]` — always link to concrete URLs.
+- **Series format is locked.** A series index can be `index.md` / `.mdx` / `README.md` / `README.mdx` / `index.rst` / `README.rst` (first match wins). All child posts must match. Mixing formats is a build error.
+- **rST needs Python `docutils`.** Set `AMYTIS_RST_PYTHON=/path/to/python` if not on `$PATH`. Without it, falls back to a lower-fidelity built-in parser.
+- **Pagefind index.** `bun run build:dev` regenerates `public/pagefind/`; search returns stale results until you rerun it after content changes.
+- **`trailingSlash: true` is load-bearing.** Lets co-located post assets (`posts/slug/images/`) coexist with `posts/slug/index.html`. Don't flip it in `next.config.ts`.
+- **Shiki highlighter is a `globalThis` singleton.** Never instantiate it per render — `createHighlighter` loads Oniguruma WASM + grammars (~1–2 s). See `src/lib/shiki.ts`.
+- **rST sanitize-html allowlist must keep `style` + `data-*` on `pre`/`code`/`span`/`div`.** Stripping any of these silently kills Shiki output (monochrome text in prod, looks fine locally because dev rST isn't sanitized). See `src/components/RstRenderer.tsx`.
+- **Bump `RST_RENDERER_DISK_CACHE_VERSION` (`src/lib/rst-renderer.ts`) on highlighter-output changes.** Stale on-disk caches in `.cache/rst-renderer/` will serve old markup otherwise. Run `rm -rf .cache/rst-renderer` after pulling such a change.
+- **Fence meta needs `rehype-fence-meta` BEFORE `rehype-raw`.** `mdast-util-to-hast` stores fence meta on `node.data.meta`, which `rehype-raw` drops during HTML round-trip. The plugin copies it to a real `data-meta` attribute first. Order matters in `MarkdownRenderer.tsx`.
+- **Code-group tabs add `<input type="radio">` + `<label>` to the rST sanitize-html allowlist.** Keep the `transformTags` guard in `RstRenderer.tsx` that strips any `<input>` whose `type !== "radio"` — that's the defense against an rST author injecting password/file/etc. inputs through raw HTML.
+- **GitHub alerts (`> [!NOTE]`, etc.) need the custom `remarkGithubAlerts` plugin.** `remark-gfm` v4 does NOT transform `[!TYPE]` blockquotes — they pass through as plain blockquotes with the literal marker visible. The custom plugin in `src/lib/remark-github-alerts.ts` is what detects them and routes to `<GithubAlert>`. If a future remark-gfm adds native alert support, that's a regression to watch for (covered by an integration test).
+- **Single-line block math `$$ x $$` is silently inline.** `micromark-extension-math` (under `remark-math` v6) requires the `$$` markers on their own lines — single-line collapses to *inline* math (no `katex-display` wrapper, no centering, no display margin) and looks like a subtly under-styled formula. `src/lib/normalize-vuepress-math.ts` expands single-line `$$ x $$` to opener / body / closer before parsing, so authored content stays portable. If a chapter formula stops centering, suspect the normalizer's regex first.
+
+## Development workflow
+
+- **Don't push or open PRs unless asked.** Local commits are fine; anything touching the remote needs explicit go-ahead.
+- **Commit in focused slices.** Keep `bun run validate` green at each commit so the branch stays bisectable.
+- **Tests + docs in the same change.** Update `docs/ARCHITECTURE.md` / `docs/CONTRIBUTING.md` / `docs/TROUBLESHOOTING.md` alongside seam/workflow/invariant changes — not as a follow-up.
+- **Commits** follow Conventional Commits: `feat | fix | refactor | perf | chore | docs | test | release`. Subject under ~70 chars; body explains *why*.
+- **Branches:** `<type>/<kebab-slug>` matching commit prefixes.
+- **No Claude attribution.** Do not add `Co-Authored-By: Claude ...` trailers to commit messages or the `🤖 Generated with [Claude Code]` footer to PR descriptions. The default templates in the harness include both — strip them.
+
+## Verifying a change
+
+- **Default verify loop: `bun run lint && bun run test` only.** Stop here.
+- **Do NOT run `bun run build:dev` (or `bun run build` / `bun run validate`) unless the user asks OR it is genuinely needed.** It takes ~1–2 minutes (Turbopack compile + 800+ static pages + Pagefind index) and the cost adds up fast across many small steps. None of these are "needed" on their own: markdown pipeline edits, schema changes, route moves, branch tip, pre-PR readiness, "just to be safe."
+- "Genuinely needed" means lint+test **cannot** catch the failure mode you're worried about — e.g. a strict-build invariant that only fires during static export (a `throw` in `generateStaticParams`, a `redirectFrom` collision, a Zod-schema failure that only triggers on real content). If unsure, prefer asking over running.
+- `bun run validate` chains lint + test + build:dev; same rule — same bar.
+- Touched `src/lib/markdown.ts`, `src/lib/urls.ts`, or `site.config.ts`? Add an integration test under `tests/integration/`.
+- Touched any dynamic route? Verify both ASCII and Unicode slugs render.
+
+## Context compression hints
+
+When compressing history, preserve in priority order:
+
+1. **Build-time invariants touched** — strict-build/throw boundaries, Zod schemas, `site.config.ts` shape, helpers in `src/lib/urls.ts` / `src/lib/markdown.ts`.
+2. **Modified files and why** — file list with one-line reasons, not the diff.
+3. **Verification status** — `bun run lint && bun test` (and `build:dev` if run) pass/fail.
+4. **Cache version bumps** — `RST_RENDERER_DISK_CACHE_VERSION` etc.; easy to lose after compression.
+5. **Open TODOs and rollback notes.**
+6. **Tool output**: drop; keep pass/fail summary only.
+
+## Where to find more
 
-## Key Components
-
-- `PostLayout` / `SimpleLayout` - Post page layouts with TOC, series sidebar, external links, comments
-- `Hero` - Configurable homepage hero section with collapsible intro
-- `HorizontalScroll` - Scrollable container with navigation arrows for featured content
-- `PostList` - Card-based post listing with thumbnails, metadata, excerpts, and tags
-- `SeriesCatalog` - Timeline-style series post listing with numbered entries and progress indicator
-- `SeriesSidebar` - Series navigation sidebar with progress bar and color-coded states
-- `SeriesList` - Mobile-optimized series navigation matching sidebar design
-- `Search` - Full-text search (Cmd/Ctrl+K) powered by Pagefind (build-time index); features type filter tabs (All/Post/Flow/Book), recent searches, keyboard navigation (arrows + number keys), debounced input, body scroll lock, focus trap, ARIA accessibility, and search syntax tips (`"phrase"`, `-exclude`)
-- `TableOfContents` - Sticky TOC with scroll tracking, reading progress, and back-to-top
-- `MarkdownRenderer` - MDX rendering with GFM, math, syntax highlighting, diagrams
-- `CoverImage` - Optimized image component with WebP support
-- `Comments` - Giscus or Disqus integration (theme-aware)
-- `Analytics` - Umami, Plausible, or Google Analytics integration
-- `FlowContent` - Client wrapper for flow pages with tag filtering state management
-- `FlowCalendarSidebar` - Calendar sidebar with date navigation, browse panel, and clickable tag filters
-- `FlowTimelineEntry` - Individual flow entry in timeline list
-- `LanguageSwitch` - i18n language selector
-- `ThemeToggle` - Light/dark mode toggle
+- `docs/ARCHITECTURE.md` — route map, content model, components, data layer, frontmatter schemas, full configuration reference
+- `docs/CONTRIBUTING.md` — full command list, test layout, content-creation scripts
+- `docs/TROUBLESHOOTING.md` — known issues (AVIF, dev-mode browser-extension CSP/SharedStorage noise)
+- `docs/deployment.md` — production deploy steps
+- `docs/guides/` — task-oriented walkthroughs (e.g. `importing-vuepress-books.md`)
+- `site.config.ts` — live config (read it directly; don't infer from this file)