@hutusi/amytis 1.5.5

package/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    name: Build & Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Run Tests
+        run: bun test
+
+      - name: Build
+        run: bun run build:dev

package/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish to npm and GitHub Packages
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # Required for Trusted Publishing
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 'lts/*'
+          registry-url: 'https://registry.npmjs.org'
+      
+      - uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+      
+      - run: bun install --frozen-lockfile
+      
+      - name: Publish to npm
+        # No NODE_AUTH_TOKEN needed for Trusted Publishing!
+        # --provenance proves that the package was built in this GitHub Action
+        run: npm publish --provenance --access public
+
+  publish-github:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 'lts/*'
+          registry-url: 'https://npm.pkg.github.com'
+          scope: '@hutusi'
+      
+      - uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+      
+      - run: bun install --frozen-lockfile
+      
+      - name: Publish to GitHub
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/AGENTS.md

@@ -0,0 +1,41 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/app/`: Next.js App Router pages and route handlers (`posts`, `series`, `tags`, `authors`, feeds, sitemap).
+- `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.
+- `tests/`: Integration/e2e/tooling suites; keep focused utility tests near source (example: `src/lib/markdown.test.ts`).
+- `scripts/`: Bun-based authoring/import tooling.
+
+## 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 lint`: Run ESLint.
+- `bun test` / `bun run test:unit` / `bun run test:int` / `bun run test:e2e`: Run all or scoped tests.
+
+## Coding Style & Naming Conventions
+- Use TypeScript for app and utility code; MDX/Markdown for content.
+- Match existing file style and let ESLint enforce consistency.
+- Naming: components in PascalCase (`PostCard.tsx`), helpers in camelCase (`getAuthorSlug`), content slugs in kebab-case unless intentionally Unicode.
+- Keep business logic in `src/lib/` and keep route files thin.
+
+## Static Export Route Rules (Important)
+- 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/中文测试文章`).
+- 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.
+- Before PR: run `bun run lint && bun test && bun run build:dev`.
+
+## Commit & Pull Request Guidelines
+- Follow Conventional Commits used in history (`feat:`, `fix:`, `refactor:`, `docs:`, `release:`).
+- Keep commits single-purpose and include impacted paths in PR description.
+- PRs should include intent, validation steps, and screenshots for UI changes.
+- CI must pass (`bun install --frozen-lockfile`, lint, test, build).

package/CLAUDE.md

@@ -0,0 +1,200 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+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.
+
+## 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 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)
+bun run clean              # Remove .next, out, public/posts directories
+
+# 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 content/series/my-series/
+bun run new-series "Series Name"      # Create new series with cover image
+bun run new-from-pdf doc.pdf          # Create post from PDF (converts pages to images)
+bun run new-from-pdf doc.pdf --title "My Document"  # 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 "My 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-flow                    # Create today's flow note (.md)
+bun run new-flow "My Title"         # Create flow with custom title
+bun run new-flow --mdx              # Use .mdx format instead
+```
+
+## 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/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, etc.)
+
+### 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.
+
+## 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
+- `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
+- `comments.provider` - 'giscus' | 'disqus' | null
+
+## Content Frontmatter
+
+### Posts
+
+```yaml
+---
+title: "Post Title"
+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
+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"
+---
+```
+
+### 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)
+---
+```
+
+### 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"
+        file: "chapter-file"           # Maps to chapter-file.mdx in same directory
+  - part: "Part II: Advanced"
+    chapters:
+      - title: "Another Chapter"
+        file: "another-chapter"
+---
+```
+
+## 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` - Client-side fuzzy search (Cmd/Ctrl+K) using Fuse.js
+- `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

package/GEMINI.md

@@ -0,0 +1,84 @@
+# Amytis Project Context
+
+## Project Overview
+**Amytis** is a high-performance, elegant digital garden and blog engine built with **Next.js 16 (App Router)**, **React 19**, and **Tailwind CSS v4**. It is designed for cultivating thoughts and sharing knowledge with a focus on typography, readability, and flexible content organization.
+
+### Main Technologies
+- **Framework**: Next.js 16 (App Router)
+- **Runtime/Package Manager**: [Bun](https://bun.sh/)
+- **Styling**: Tailwind CSS v4 with CSS-variable based themes and `@tailwindcss/typography`.
+- **Content**: Local MDX/Markdown files with Zod-validated frontmatter.
+- **Search**: Client-side fuzzy search using `Fuse.js`.
+- **Diagrams**: Native support for `Mermaid` diagrams.
+- **Math**: LaTeX support via `rehype-katex`.
+
+## Building and Running
+
+### Development
+```bash
+bun dev
+```
+
+### Production Build (Static Export)
+```bash
+bun run build
+```
+Generates a fully optimized static site in the `out/` directory.
+
+### Linting & Testing
+```bash
+bun run lint
+bun test
+```
+
+## Project Structure
+- `src/app/`: Next.js App Router pages and global styles.
+  - `page.tsx`: Homepage with horizontal scrolling featured sections and latest timeline.
+  - `posts/`: Paginated post listing and individual post routes.
+  - `flows/`: Stream-style daily notes or micro-blogging (`[year]/[month]/[day]`).
+  - `series/`: Series overview and individual series catalog pages with pagination support.
+  - `archive/`: Timeline-based chronological archive grouped by year and month.
+  - `tags/`: Popularity-sorted tag cloud and filtered listings.
+  - `authors/`: Posts filtered by individual authors.
+  - `search.json/`: Static search index generator.
+- `src/lib/`: Core logic and utilities.
+  - `markdown.ts`: Advanced parsing for posts/series/flows, sorting, reading time calculation (multilingual), and metadata inheritance.
+- `src/components/`: Modular UI blocks (Hero, HorizontalScroll, Search, CoverImage, etc.).
+- `content/`: Source Markdown/MDX content.
+- `scripts/`: CLI tools for content management and asset processing.
+
+## Key Features & Configuration
+
+### Advanced Content Management
+- **Posts**: Supports both flat files (`.mdx`) and nested folders (`/index.mdx`) with co-located assets.
+- **Flows**: Daily notes or micro-posts organized by date (`YYYY/MM/DD`). Designed for quick thoughts and stream-of-consciousness updates.
+- **Series**: 
+  - Robust grouping with folder-based or file-based entries.
+  - Configurable sorting: `date-asc`, `date-desc`, or `manual` (explicit list of slugs).
+  - Cross-referencing: Series can include posts from the general pool or other folders.
+  - Metadata inheritance: Posts can inherit attributes (like authors) from series index files.
+- **Featured Content**: Mark posts or series as `featured` to display them in prominent homepage sections with horizontal scrolling.
+- **Cover Images**: Support for local paths, external URLs, and dynamic desaturated gradients (`text:Label`).
+- **External Links**: Posts can include a list of curated external resources in frontmatter.
+
+### Refined UX & Design
+- **Homepage**: Elegant layout with "Curated Series" and "Featured Stories" sections using horizontal scroll triggers.
+- **Navigation**: Command+K fuzzy search, sticky TOC with progress tracking, and Series Catalog sidebars.
+- **Theming**: Four built-in palettes (`default`, `blue`, `rose`, `amber`) with high-contrast Dark Mode support.
+- **i18n**: Multi-language infrastructure (en, zh) with footer language switcher. `site.config.ts` supports localized strings.
+
+### Build Pipeline
+- **Asset Mapping**: `scripts/copy-assets.ts` mirrors content assets to the public folder, handling relative path resolution for both flat and nested structures.
+- **Image Optimization**: Fully integrated with `next-image-export-optimizer` for optimized WebP delivery in static exports.
+
+## Recent Updates
+- Added **Flows** feature: a stream for daily notes and micro-blogging.
+- Upgraded to Next.js 16.1.1 and React 19.
+- Implemented robust series sorting and manual selection logic.
+- Refined homepage layout with horizontal scrolling and distinct card styles for Series, Featured, and Latest sections.
+- Added comprehensive CLI tools for PDF and Image-to-post conversions.
+- Unified simple page layouts (About, Tags, Archive) for visual consistency.
+- Resolved text-rendering cover image display issues using stable utility classes.
+- Added pagination to the main posts list and individual series pages.
+- Implemented sophisticated reading time calculation for mixed Latin and CJK text.
+- Enhanced author management with metadata inheritance and slug-based routing.

package/README.md

@@ -0,0 +1,172 @@
+# 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.
+
+[**Live Demo**](https://amytis.vercel.app/)
+
+![Amytis Screenshot](public/screenshot.png)
+
+## Features
+
+- **Digital Garden Philosophy:** Non-linear navigation through tags, series, authors, books, flows, and chronological archives.
+- **Fuzzy Search:** Instant, client-side search across all posts (Cmd/Ctrl+K) powered by Fuse.js.
+- **Structured Content:**
+  - **Series:** Multi-part content organization with manual or automatic ordering.
+  - **Books:** Long-form content with explicit chapters, parts, and a dedicated reading interface.
+  - **Flows:** Stream-style daily notes or micro-blogging for quick thoughts.
+- **Rich MDX Content:**
+  - GitHub Flavored Markdown (tables, task lists, strikethrough).
+  - Syntax-highlighted code blocks.
+  - Mermaid diagrams (flowcharts, sequence diagrams, etc.).
+  - LaTeX math via KaTeX.
+  - Raw HTML support for custom layouts.
+- **Elegant Design:**
+  - Minimalist aesthetic with high-contrast typography.
+  - Light/Dark mode with automatic system detection.
+  - Four color palettes: default (emerald), blue, rose, amber.
+  - Responsive layout optimized for reading.
+  - Horizontal scrolling for featured content on the homepage.
+- **Table of Contents:** Sticky TOC with scroll tracking, reading progress indicator, and active heading highlight.
+- **Flexible Content Structure:**
+  - Flat files (`post.mdx`) or nested folders (`post/index.mdx`).
+  - 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.
+- **Performance & SEO:**
+  - Fully static export with optimized WebP images.
+  - Native sitemap and RSS feed generation.
+  - Multilingual reading time estimate (supports Latin and CJK).
+- **Integrations:**
+  - Analytics: Umami, Plausible, or Google Analytics.
+  - Comments: Giscus (GitHub Discussions) or Disqus.
+  - Internationalization: multi-language support (en, zh) with localized `site.config.ts`.
+- **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.
+
+## Quick Start
+
+1. **Install Dependencies:**
+   ```bash
+   bun install
+   ```
+
+2. **Start Development Server:**
+   ```bash
+   bun dev
+   ```
+   Visit [http://localhost:3000](http://localhost:3000).
+
+3. **Build for Production (Static Export):**
+   ```bash
+   bun run build
+   ```
+   The static site will be generated in the `out/` directory with optimized images.
+
+4. **Development Build (faster, no image optimization):**
+   ```bash
+   bun run build:dev
+   ```
+
+## 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
+```
+
+## Configuration
+
+All site settings are managed in `site.config.ts`:
+
+```typescript
+export const siteConfig = {
+  // ...
+  nav: [
+    { name: "Home", url: "/", weight: 1 },
+    { name: "Flow", url: "/flows", weight: 1.1 }, // Add Flows to nav
+    { name: "Series", url: "/series", weight: 1.5 },
+    { name: "Books", url: "/books", weight: 1.7 },
+    { name: "Archive", url: "/archive", weight: 2 },
+    // ...
+  ],
+  // ...
+  flows: {
+    recentCount: 5,
+  },
+};
+```
+
+## Writing Content
+
+### Posts
+
+Create `.md` or `.mdx` files in `content/posts/`.
+
+### Flows
+
+Create daily notes in `content/flows/YYYY/MM/DD.mdx` or `content/flows/YYYY/MM/DD/index.mdx`.
+
+### Series
+
+Create a directory in `content/series/` with an `index.mdx`.
+
+### Books
+
+Books are for long-form, structured content. Create a directory in `content/books/`.
+
+## Project Structure
+
+```
+amytis/
+  content/
+    posts/              # Blog posts
+    series/             # Series collections
+    books/              # Long-form books
+    flows/              # Daily notes (YYYY/MM/DD)
+    about.mdx           # Static pages
+  public/               # Static assets
+  src/
+    app/                # Next.js App Router pages
+      books/            # Book routes
+      flows/            # Flow routes
+    components/         # React components
+    lib/
+      markdown.ts       # Data access layer
+```
+
+## Documentation
+
+- [Architecture Overview](docs/ARCHITECTURE.md)
+- [Contributing Guide](docs/CONTRIBUTING.md)
+
+## License
+
+MIT

package/TODO.md

@@ -0,0 +1,76 @@
+# Future Roadmap
+
+## 🚀 High Priority (Next Steps)
+
+- [ ] **User Experience (UX)**
+  - [ ] **Code Blocks**: Add a "Copy to Clipboard" button.
+  - [ ] **Images**: Implement a Lightbox or Zoom-on-click feature.
+  - [ ] **Navigation**: Add Breadcrumbs (e.g., `Home > Category > Post`).
+  - [ ] **Navigation**: Add Previous/Next post links at the bottom of articles.
+
+## 🌿 Digital Garden Features
+
+- [ ] **Knowledge Graph**:
+  - [ ] **Backlinks**: Show "Pages that link here" at the bottom of posts.
+  - [ ] **Wiki-links**: Support `[[Internal Link]]` syntax.
+
+## 🔮 Future Enhancements
+
+- [ ] **Performance & App**
+  - [ ] **PWA**: Add `manifest.json` and service workers for offline support.
+  - [ ] **Search Optimization**: Optimize search index for large gardens (e.g. content segmentation).
+
+- [ ] **Visuals**
+  - [ ] **Dynamic OG Images**: Generate custom social cards with post title using `@vercel/og` (Satori).
+
+- [ ] **CLI Enhancements**
+  - [ ] **Interactive Mode**: Use prompts to select series, tags, and layouts when creating new posts.
+
+## ✅ Completed
+
+- [x] **Content Types**
+  - [x] **Flows**: Stream-style daily notes or micro-blogging.
+  - [x] **Books**: Structured long-form content with chapters.
+
+- [x] **Engagement**
+  - [x] **Comments**: Integrate Giscus (GitHub Discussions) for comments.
+
+- [x] **Engineering**
+  - [x] **Validation**: Add Zod schema validation for content frontmatter to prevent build errors.
+  - [x] **Testing**: Add E2E tests for the new search and navigation features.
+
+- [x] **SEO & Discovery**
+  - [x] Generate `sitemap.xml` for search engines.
+  - [x] Generate `rss.xml` / `atom.xml` for feed readers.
+  - [x] Add Open Graph (OG) meta tags for social sharing.
+
+- [x] **Navigation & UX**
+  - [x] Implement a client-side fuzzy Search bar (Command+K).
+  - [x] Add a sticky Table of Contents (TOC) with Unicode/Multilingual support.
+  - [x] Add "Reading Time" estimate to post headers.
+  - [x] Refine link styling (clean default, underline on hover).
+  - [x] **Hero Section**: Configurable, collapsible welcome mat.
+  - [x] **Themes**: Configurable color palettes (default, blue, rose, amber).
+  - [x] **i18n**: Client-side language switcher infrastructure.
+
+- [x] **Content & Architecture**
+  - [x] **Series**: Robust support for grouping related posts (file-based & folder-based).
+  - [x] **Series**: Manual sorting, cross-referencing, and configurable order.
+  - [x] **Related Posts**: Auto-suggest relevant articles.
+  - [x] **Cover Images**: Support local paths, external URLs, and generated text covers.
+  - [x] **Analytics**: Privacy-friendly configuration (Umami/Plausible/Google).
+
+- [x] **Performance**
+  - [x] Static Image Optimization (`next-image-export-optimizer`).
+  - [x] Automated image dimension injection.
+
+- [x] **CLI Tools**
+  - [x] `bun run new` script for scaffolding posts.
+  - [x] `bun run new-series` script for scaffolding series.
+
+- [x] **UI Polish & Refinements**
+  - [x] **Animations**: Define missing animation classes.
+  - [x] **Color Contrast**: Improve accessibility.
+  - [x] **Responsive Grids**: Improve mobile/tablet layouts.
+  - [x] **Archive Timeline**: Refine CSS.
+  - [x] **Loading States**: Add skeleton loaders.