@hutusi/amytis 1.9.0 → 1.11.0

package/.entire/settings.json

@@ -0,0 +1,4 @@
+{
+  "enabled": true,
+  "telemetry": false
+}

package/AGENTS.md

@@ -1,21 +1,25 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-- `src/app/`: Next.js App Router pages and route handlers (`posts`, `series`, `tags`, `authors`, feeds, sitemap).
+- `src/app/`: Next.js App Router pages and route handlers (`posts`, `series`, `books`, `flows`, `notes`, `tags`, `authors`, feeds, graph, sitemap, custom `[slug]` routes).
 - `src/components/`: Reusable UI building blocks (cards, navigation, search, i18n/theme controls).
-- `src/lib/`: Content parsing and shared logic (`markdown.ts`, i18n helpers, rehype utilities).
-- `content/posts/`, `content/series/`: Markdown/MDX source content. Use folder posts (`index.mdx` + `images/` or `assets/`) when media is co-located.
+- `src/lib/`: Content parsing and shared logic (`markdown.ts`, feed helpers, URL helpers, rehype/remark utilities).
+- `content/`: Markdown/MDX source content for posts, series, books, notes, flows, and static pages. Use folder posts (`index.mdx` + `images/` or `assets/`) when media is co-located.
 - `tests/`: Integration/e2e/tooling suites; keep focused utility tests near source (example: `src/lib/markdown.test.ts`).
 - `scripts/`: Bun-based authoring/import tooling.
+- `packages/create-amytis/`: The `bun create amytis` scaffold CLI; keep its tests aligned with repo scaffolding behavior.
 
 ## Build, Test, and Development Commands
 - `bun install`: Install dependencies.
 - `bun dev`: Run local dev server at `http://localhost:3000`.
-- `bun run build`: Production export build (asset copy + Next build + image optimizer).
-- `bun run build:dev`: Build without export image optimization.
-- `bun run clean`: Remove generated outputs (`.next`, `out`, `public/posts`).
+- `bun run build`: Production export build (copy assets, generate graph, Next build, optimize images, generate Pagefind index in `out/pagefind`).
+- `bun run build:dev`: Build without export image optimization and generate the dev search index in `public/pagefind`.
+- `bun run build:graph`: Regenerate the knowledge graph data.
+- `bun run validate`: Run the recommended pre-PR validation sequence (`lint`, `test`, `build:dev`).
+- `bun run clean`: Remove generated outputs (`.next`, `out`, `public/posts`, `public/books`, `public/flows`).
 - `bun run lint`: Run ESLint.
 - `bun test` / `bun run test:unit` / `bun run test:int` / `bun run test:e2e`: Run all or scoped tests.
+- Content tooling: `bun run new`, `bun run new-weekly`, `bun run new-series`, `bun run new-note`, `bun run new-flow`, `bun run new-flow-from-chat`, `bun run new-from-pdf`, `bun run new-from-images`, `bun run import-book`, `bun run sync-book`, `bun run series-draft`.
 
 ## Coding Style & Naming Conventions
 - Use TypeScript for app and utility code; MDX/Markdown for content.
@@ -27,12 +31,14 @@
 - Project uses `output: "export"` and `trailingSlash: true` in `next.config.ts`.
 - In `generateStaticParams()`, return raw segment values; do not pre-encode with `encodeURIComponent`.
 - Never link to route placeholders like `/posts/[slug]`; always link to concrete slugs (for example, `/posts/中文测试文章`).
+- Posts may also resolve through custom top-level paths via `series.customPaths` and `[slug]/[postSlug]`; preserve those URL helpers instead of hardcoding paths.
 - When touching dynamic routes, verify both ASCII and Unicode paths.
 
 ## Testing Guidelines
 - Test framework: Bun (`bun:test`). File pattern: `*.test.ts`.
-- Add tests when changing slug resolution, content parsing, routing, or scaffolding scripts.
+- Add tests when changing slug resolution, content parsing, routing, feed generation, or scaffolding scripts.
 - Before PR: run `bun run lint && bun test && bun run build:dev`.
+- Search in local dev depends on the Pagefind output from `bun run build:dev`; regenerate it when changing content or search behavior.
 
 ## Commit & Pull Request Guidelines
 - Follow Conventional Commits used in history (`feat:`, `fix:`, `refactor:`, `docs:`, `release:`).

package/CHANGELOG.md

@@ -5,6 +5,47 @@ 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.11.0] - 2026-03-07
+
+### Changed
+- **Feed Output Quality**: RSS and Atom feeds now render Markdown content as HTML, include richer item metadata, and send explicit cache headers for static deployments.
+- **Metadata Consistency**: Consolidated image URL resolution so Open Graph and JSON-LD metadata use the same asset handling logic.
+- **Documentation Sync**: Updated the English and Chinese READMEs plus contributor guidance to reflect current scaffolding behavior, dev-search setup, and workspace instructions.
+
+### Fixed
+- **RSS Standards Compliance**: Corrected the RSS MIME type to `application/rss+xml` and improved RSS/Atom structure for better reader compatibility.
+- **Feed Metadata Fidelity**: Improved handling of author fields, item content, and image metadata across feed generation and social preview output.
+- **Post Page Polish**: Improved post page OG images, previous/next navigation consistency, and TOC indentation.
+- **Book Link Consistency**: Standardized book links to use the shared URL helper.
+
+### Docs
+- **Developer Notes**: Added inline documentation for `getFeedItems()` behavior and configuration handling.
+- **Repository Instructions**: Refreshed repository-level agent instructions to match the current workspace layout and release workflow.
+
+## [1.10.0] - 2026-03-02
+
+### Added
+- **Configurable URL Topology**: Added support for `posts.basePath` and `series.customPaths` so posts and series can be served under custom prefixes.
+- **Single-Language Mode**: Added `i18n.enabled` to disable multilingual routing/UI when running a single-locale site.
+- **Homepage Content Controls**: Added pinned-post support and optional post subtitles for improved featured and latest sections.
+- **Author Profile Expansion**: Added configurable default authors plus optional author avatar/social images and header/card visibility toggles.
+- **Publishing Controls**: Added `posts.excludeFromListing` to keep selected series posts out of the main `/posts` feed.
+- **Deployment & Media**: Added one-command Linux/nginx deploy script and `images.cdnBaseUrl` support for serving images from a CDN.
+- **Branding Controls**: Added configurable logo and favicon paths in `site.config.ts`.
+
+### Changed
+- **Homepage Design System**: Refined homepage layout and card hierarchy across hero, featured content, latest writing, and series sections.
+- **Subscribe Surface**: Moved `/subscribe` to content-driven authoring so users can fully edit subscription copy in Markdown/MDX.
+- **Documentation**: Updated architecture, deployment, and configuration guides to reflect current routing and feature behavior.
+
+### Fixed
+- **Static Export Stability**: Fixed `output: "export"` edge cases by returning placeholder params for empty/disabled dynamic routes.
+- **Dynamic Routing Conflicts**: Resolved route naming and generation conflicts for custom prefixes and static params.
+- **Navigation Consistency**: Fixed mismatch between navigation post URL and configured posts base path.
+- **Book Route Safety**: Prevented invalid book chapter params by validating chapter existence before route generation.
+- **Image Handling**: Fixed markdown image path resolution across content types and ensured CDN prefixing is applied consistently.
+- **Rendering & Type Safety**: Fixed TypeScript handling for custom `rss-feed` element and addressed dev-time WebP 404 behavior.
+
 ## [1.9.0] - 2026-02-28
 
 ### Added

package/CLAUDE.md

@@ -25,6 +25,9 @@ bun run build              # Full production build (copies assets, builds Next.j
 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
@@ -49,6 +52,7 @@ bun run sync-book <slug>              # Sync chapters list for one book
 
 - `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
@@ -74,7 +78,9 @@ bun run sync-book <slug>              # Sync chapters list for one book
 - `/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, etc.)
+- `/[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
 
@@ -90,20 +96,40 @@ bun run sync-book <slug>              # Sync chapters list for one book
 
 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.provider` - 'umami' | 'plausible' | 'google' | null
+- `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
 
@@ -112,6 +138,7 @@ Key configuration options:
 ```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"
@@ -120,6 +147,7 @@ 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

package/README.md

@@ -1,10 +1,23 @@
 # Amytis
 
-**Amytis** is a high-performance, elegant digital garden built with Next.js 16, React 19, and Tailwind CSS v4. It is designed for cultivating thoughts, sharing knowledge, and growing ideas with a focus on typography and readability.
+[English](README.md) | [简体中文](README.zh.md)
+
+**Amytis** is an elegant, open-source framework for building a personal digital garden: a living knowledge space where ideas grow from raw notes to refined writing. It is built with Next.js 16, React 19, and Tailwind CSS v4, with a strong focus on readability, structure, and long-term content ownership.
 
 [**Live Demo**](https://amytis.vercel.app/)
 
-![Amytis Screenshot](public/screenshot.png)
+![Amytis Screenshot](public/images/amytis-screenshot.jpg)
+
+## The Knowledge Ladder
+
+Amytis is built around a simple path from rough to refined:
+
+- **Flow**: Capture raw daily thoughts and fragments.
+- **Articles**: Refine one idea into a clear essay.
+- **Series**: Connect related articles into a curated narrative.
+- **Books**: Distill mature knowledge into structured chapters and parts.
+
+Each stage builds on the previous one, so your garden can evolve naturally.
 
 ## Features
 
@@ -37,9 +50,13 @@
   - Co-located assets: keep images inside post folders (`./images/`).
   - Date-prefixed filenames: `2026-01-01-my-post.mdx`.
   - Draft support for posts, series, books, and flows.
+- **Author Ecosystem:** Per-author profile pages with bio, avatar, and social links. Posts are filterable by author; an optional author card appears at the end of each post.
 - **Performance & SEO:**
   - Fully static export with optimized WebP images.
-  - Native sitemap and RSS feed generation.
+  - Open Graph and Twitter card metadata for every content type.
+  - JSON-LD structured data (`BlogPosting`, `Book`, `Article`) for Google rich results.
+  - RSS/Atom feed with configurable format (`rss` | `atom` | `both`) and content depth (`full` | `excerpt`).
+  - Feed auto-discovery links in `<head>`, native sitemap generation.
   - Multilingual reading time estimate (supports Latin and CJK).
 - **Integrations:**
   - Analytics: Umami, Plausible, or Google Analytics.
@@ -48,8 +65,30 @@
 - **Content CLI Tools:** Create posts, series, and import from PDFs or image folders.
 - **Modern Stack:** Next.js 16, React 19, Tailwind CSS v4, TypeScript 5, Bun.
 
+## Design Philosophy
+
+- **Elegance by default**: Typography, spacing, and color should feel intentional out of the box.
+- **Content over configuration**: Writing and publishing should be simple file-based workflows, not CMS-heavy setup.
+- **Markdown-first, not markdown-limited**: Keep authoring portable while supporting rich output (math, diagrams, code, wikilinks).
+- **Ship what you need**: Features are modular through `site.config.ts`; disable sections you do not use.
+- **Plain text, long-term ownership**: Content stays in Markdown/MDX so it remains versionable and portable.
+
 ## Quick Start
 
+### New Project (Recommended)
+
+Scaffold a new Amytis site with one command:
+
+```bash
+bun create amytis my-garden
+cd my-garden
+bun dev
+```
+
+The scaffold command downloads the latest tagged Amytis release, installs dependencies, and patches `site.config.ts` and `package.json` with your project metadata.
+
+### Clone & Run
+
 1. **Install Dependencies:**
    ```bash
    bun install
@@ -61,6 +100,8 @@
    ```
    Visit [http://localhost:3000](http://localhost:3000).
 
+   > **Search in dev:** the Pagefind index is generated during `bun run build:dev`. Run it once before testing Cmd/Ctrl+K locally, and re-run it after content changes.
+
 3. **Build for Production (Static Export):**
    ```bash
    bun run build
@@ -75,67 +116,49 @@
 ## CLI Commands
 
 ```bash
-# Development
-bun dev                    # Start dev server at localhost:3000
-bun run lint               # Run ESLint
-
-# Build
-bun run build              # Full production build (copy assets + Next.js build + image optimization)
-bun run build:dev          # Development build (no image optimization, faster)
-bun run clean              # Remove .next, out, public/posts directories
-
-# 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
-
-# Content creation
-bun run new "Post Title"                          # Create new post (flat file)
-bun run new "Title" --folder                      # Create as folder with index.mdx
-bun run new "Title" --prefix weekly               # Create with prefix (e.g., weekly-title)
-bun run new "Title" --template custom             # Use custom template from templates/
-bun run new "Title" --md                          # Create as .md instead of .mdx
-bun run new "Title" --series my-series            # Create post in a series directory
-bun run new-series "Series Name"                  # Create new series with cover image placeholder
-bun run new-from-pdf doc.pdf                      # Create post from PDF (converts pages to images)
-bun run new-from-pdf doc.pdf --title "My Doc"     # With custom title
-bun run new-from-pdf doc.pdf --scale 3.0          # Higher resolution (default: 2.0)
-bun run new-from-images ./photos                  # Create post from image folder
-bun run new-from-images ./photos --title "Gallery" # With custom title
-bun run new-from-images ./photos --sort date      # Sort by date (default: name)
-bun run new-from-images ./photos --no-copy        # Reference images instead of copying
-bun run new-note "Concept"                        # Create a new atomic note
-bun run new-flow-from-chat                        # Import all new files in imports/chats/
-bun run sync-book                                 # Sync book chapters with files on disk
-bun run series-draft "series-slug"                # Set all posts in a series to draft
-bun run series-draft "series-slug" --undraft      # Remove draft status from series posts
+## Core
+bun dev
+bun run lint
+bun run validate
+
+## Build & Deploy
+bun run build
+bun run build:dev
+bun run clean
+bun run deploy                 # Deploy to Linux/nginx server (requires .env.local)
+
+## Test
+bun test
+bun run test:unit
+bun run test:int
+bun run test:e2e
+
+## Create Content
+bun run new "Post Title"
+bun run new-weekly "Weekly Topic"
+bun run new-series "Series Name"
+bun run new-note "Concept"
+bun run new-flow
+
+## Import / Maintain
+bun run new-from-pdf ./doc.pdf
+bun run new-from-images ./photos
+bun run new-flow-from-chat
+bun run import-book
+bun run sync-book
+bun run series-draft "series-slug"
 ```
 
 ### Importing Chat Logs to Flows
 
-Amytis includes a powerful script to convert chat logs (like those from LLMs or messaging apps) into Flow entries.
+Drop `.txt` or `.log` files into `imports/chats/`, then run:
 
-1. Place your `.txt` or `.log` files in `imports/chats/`.
-2. Ensure the format is:
-   ```
-   Author Name YYYY-MM-DD HH:mm:ss
-   Message content line 1
-   Message content line 2
-   ```
-3. Run the importer:
-   ```bash
-   bun run new-flow-from-chat
-   ```
-
-Options:
-- `--all`: Re-import every file (ignores history).
-- `--dry-run`: Preview changes without writing files.
-- `--author "Name"`: Only include messages from a specific author.
-- `--append`: Append to existing flow files instead of skipping.
-- `--timestamp`: Include timestamps in the rendered blocks.
+```bash
+bun run new-flow-from-chat
+```
 
-Import history is tracked in `imports/chats/.imported`.
+Common flags: `--all`, `--dry-run`, `--author "Name"`, `--append`, `--timestamp`.
+Import history is stored in `imports/chats/.imported`.
 
 ## Configuration
 
@@ -202,12 +225,15 @@ amytis/
     components/         # React components
     lib/
       markdown.ts       # Data access layer
+  packages/
+    create-amytis/      # `bun create amytis` scaffold CLI
   site.config.ts        # Site configuration
 ```
 
 ## Documentation
 
 - [Architecture Overview](docs/ARCHITECTURE.md)
+- [Deployment Guide](docs/deployment.md)
 - [Digital Garden Guide](docs/DIGITAL_GARDEN.md)
 - [Contributing Guide](docs/CONTRIBUTING.md)
 

package/README.zh.md

@@ -0,0 +1,195 @@
+# Amytis
+
+[English](README.md) | [简体中文](README.zh.md)
+
+**Amytis** 是一个优雅的开源数字花园框架，用于构建个人知识空间。它基于 Next.js 16、React 19 和 Tailwind CSS v4，强调可读性、结构化表达与长期内容所有权。
+
+[**在线演示**](https://amytis.vercel.app/)
+
+![Amytis 截图](public/images/amytis-screenshot.jpg)
+
+## 知识阶梯
+
+Amytis 围绕一条从粗糙到精炼的知识路径构建：
+
+- **Flow（随笔）**：记录每日想法与碎片。
+- **Articles（文章）**：将单个想法打磨成清晰文章。
+- **Series（系列）**：把相关文章串联为一条主题叙事。
+- **Books（书籍）**：将成熟知识沉淀为章节化结构。
+
+每个阶段都建立在上一阶段之上，花园会自然生长。
+
+## 功能特性
+
+- **数字花园体验**：通过标签、系列、作者、书籍、Flow 和归档进行非线性导航。
+- **互联知识网络**：
+  - **双向链接**：支持 `[[Slug]]` 跨内容类型关联。
+  - **反向链接**：在笔记页自动显示“Linked References”。
+  - **知识图谱**：以可视化方式展示内容连接关系。
+- **全文搜索**：基于 Pagefind 的静态搜索，支持 Cmd/Ctrl+K 快捷键。
+- **结构化内容体系**：
+  - **Series**：支持手动或自动排序的多篇集合。
+  - **Books**：支持章节与分部的长篇阅读界面。
+  - **Notes**：原子化常青笔记。
+  - **Flows**：流式日记/微记录。
+- **富文本 MDX 能力**：
+  - GitHub Flavored Markdown（表格、任务列表等）
+  - 代码高亮
+  - Mermaid 图表
+  - KaTeX 数学公式
+  - 原生 HTML 支持
+- **阅读体验与设计**：
+  - 高可读排版与响应式布局
+  - 自动系统主题检测（明/暗）
+  - 四套配色主题：default、blue、rose、amber
+  - 吸顶目录与阅读进度跟踪
+- **作者生态**：每位作者有独立主页，包含简介、头像与社交链接。文章支持按作者筛选，并可在文末显示作者卡片。
+- **性能与 SEO**：
+  - 全静态导出与 WebP 优化
+  - 每种内容类型均有完整的 Open Graph 与 Twitter Card 元数据
+  - JSON-LD 结构化数据（`BlogPosting`、`Book`、`Article`），支持 Google 富媒体搜索结果
+  - RSS/Atom 订阅源，格式（`rss` | `atom` | `both`）与内容深度（`full` | `excerpt`）可配置
+  - `<head>` 自动注入 Feed 发现链接，原生 sitemap 生成
+  - 支持 Latin/CJK 的多语言阅读时长估算
+- **集成能力**：
+  - 统计：Umami / Plausible / Google Analytics
+  - 评论：Giscus / Disqus
+  - i18n：`site.config.ts` 中配置多语言（en / zh）
+
+## 设计理念
+
+- **默认优雅**：排版、间距、色彩开箱即用且有审美一致性。
+- **内容优先**：通过文件化写作与发布流程完成创作，不依赖重型 CMS。
+- **Markdown 优先但不受限**：保持可迁移写作体验，同时支持数学、图表、代码和双向链接。
+- **按需启用**：`site.config.ts` 提供模块化开关，仅启用你需要的能力。
+- **纯文本长期所有权**：内容存储于 Markdown/MDX，便于版本管理与长期迁移。
+
+## 快速开始
+
+### 新建项目（推荐）
+
+一条命令创建新的 Amytis 站点：
+
+```bash
+bun create amytis my-garden
+cd my-garden
+bun dev
+```
+
+该脚手架会下载最新发布版 Amytis，自动安装依赖，并根据你的项目信息更新 `site.config.ts` 和 `package.json`。
+
+### 克隆运行
+
+1. **安装依赖**
+   ```bash
+   bun install
+   ```
+
+2. **启动开发环境**
+   ```bash
+   bun dev
+   ```
+   打开 [http://localhost:3000](http://localhost:3000)。
+
+   > **本地搜索说明：** Pagefind 索引是在执行 `bun run build:dev` 时生成的。本地测试 Cmd/Ctrl+K 前先运行一次；内容更新后也需要重新生成。
+
+3. **生产构建（静态导出）**
+   ```bash
+   bun run build
+   ```
+   产物位于 `out/` 目录。
+
+4. **开发构建（更快，无图片优化）**
+   ```bash
+   bun run build:dev
+   ```
+
+## CLI 命令
+
+```bash
+## Core
+bun dev
+bun run lint
+bun run validate
+
+## Build & Deploy
+bun run build
+bun run build:dev
+bun run clean
+bun run deploy                 # 部署到 Linux/nginx 服务器（需要 .env.local 配置）
+
+## Test
+bun test
+bun run test:unit
+bun run test:int
+bun run test:e2e
+
+## Create Content
+bun run new "Post Title"
+bun run new-weekly "Weekly Topic"
+bun run new-series "Series Name"
+bun run new-note "Concept"
+bun run new-flow
+
+## Import / Maintain
+bun run new-from-pdf ./doc.pdf
+bun run new-from-images ./photos
+bun run new-flow-from-chat
+bun run import-book
+bun run sync-book
+bun run series-draft "series-slug"
+```
+
+### 导入聊天记录到 Flows
+
+将 `.txt` 或 `.log` 文件放入 `imports/chats/` 后执行：
+
+```bash
+bun run new-flow-from-chat
+```
+
+常用参数：`--all`、`--dry-run`、`--author "Name"`、`--append`、`--timestamp`。  
+导入历史记录位于 `imports/chats/.imported`。
+
+## 配置
+
+所有站点配置集中在 `site.config.ts`。
+
+## 内容写作
+
+- **Posts**：创建到 `content/posts/`
+- **Flows**：创建到 `content/flows/YYYY/MM/DD.mdx`（或文件夹模式）
+- **Series**：创建 `content/series/<slug>/index.mdx`
+- **Books**：创建到 `content/books/<slug>/`
+- **Notes**：创建到 `content/notes/`，支持 `[[wiki-links]]`
+
+## 项目结构
+
+```text
+amytis/
+  content/
+    posts/
+    series/
+    books/
+    notes/
+    flows/
+  public/
+  src/
+    app/
+    components/
+    lib/
+  packages/
+    create-amytis/
+  site.config.ts
+```
+
+## 文档
+
+- [架构说明](docs/ARCHITECTURE.md)
+- [部署指南](docs/deployment.md)
+- [数字花园指南](docs/DIGITAL_GARDEN.md)
+- [贡献指南](docs/CONTRIBUTING.md)
+
+## 许可证
+
+MIT

package/TODO.md

@@ -1,18 +1,19 @@
 # Amytis Roadmap
 
 ## 🚀 Priority UX & Engineering
-- [ ] **Image Zoom**: Implement medium-zoom or a lightbox for MDX images.
 - [ ] **Breadcrumbs**: Extend Flow breadcrumbs to standard Posts and Books.
 - [ ] **Dynamic OG**: Generate automated social cards with Satori for every post.
 - [ ] **PWA Support**: Add manifest and service worker for offline reading.
-- [ ] **SEO Boost**: Implement JSON-LD structured data for Articles, Books, and Breadcrumbs.
+- [ ] **Image Zoom**: Implement medium-zoom or a lightbox for MDX images.
 
 ## 🌿 Digital Garden Evolution
-- [ ] **Knowledge Graph**: 
+- [ ] **Knowledge Graph**:
   - [ ] Interactive fullscreen mode for the graph.
   - [ ] Filter graph by tags or content types.
   - [ ] "Local Graph" view in the sidebar of individual notes.
-- [ ] **Discovery**: 
+- [ ] **Hover Preview**: Show a floating excerpt card when hovering over wiki-links, without navigating away.
+- [ ] **Transclusion**: Embed another note or post's content inline using `![[slug]]` syntax.
+- [ ] **Discovery**:
   - [ ] "On this day" section for Flows (history from previous years).
   - [ ] RSS/Atom feeds for specific categories or tags.
 - [ ] **Notes**: Support for un-linked mentions (searching for note titles in plain text).
@@ -23,6 +24,7 @@
 - [ ] **Optimization**: Automatically compress and resize co-located images during build.
 
 ## ✅ Completed Highlights
+- [x] **JSON-LD Structured Data**: `BlogPosting`, `Book`, and `Article` schemas for Google rich results.
 - [x] **Digital Garden**: Notes, Wiki-links, Backlinks, and interactive Knowledge Graph.
 - [x] **Pagefind Search**: High-performance static full-text indexing with rich UI.
 - [x] **Smart Navigation**: Persistent "Previous" and "Next" article links on all posts.