@hutusi/amytis 1.13.0 → 1.15.0

package/content/flows/2026/03/05.md

@@ -1,4 +1,5 @@
 ---
+title: 'JSDoc type comments'
 tags: ["typescript", "tooling"]
 ---
 

package/content/flows/2026/03/07.md

@@ -2,6 +2,8 @@
 tags: ["ai", "workflow"]
 ---
 
+# Using Claude Code
+
 Been using Claude Code for a week now as a daily coding assistant. A few observations so far.
 
 It is most useful for tasks where the shape of the solution is clear but the execution is tedious — refactoring, writing tests, tracking down why a CSS rule isn't applying. For genuinely novel design problems, talking through the approach matters more than generating code.

package/content/series/modern-web-dev/index.mdx

@@ -5,9 +5,11 @@ excerpt: "A curated path through modern web development: JavaScript fundamentals
 date: "2026-03-01"
 featured: true
 items:
-  - post: asynchronous-javascript
-  - post: understanding-react-hooks
+  - post: posts/asynchronous-javascript
+  - post: posts/understanding-react-hooks
   - series: nextjs-deep-dive
+  - post: markdown-showcase/中文测试文章
+  - post: digital-garden/02-architecture
 ---
 
 This collection assembles the essential reading for anyone building modern web applications. Start with the JavaScript fundamentals that underpin everything, move into React patterns, then go deep on Next.js.

package/content/series/rst-legacy/deeper-notes/images/test.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="160" height="80" viewBox="0 0 160 80">
+  <rect width="160" height="80" rx="10" fill="#d7efe3"/>
+  <text x="80" y="48" text-anchor="middle" font-family="sans-serif" font-size="18" fill="#21543d">rST</text>
+</svg>

package/content/series/rst-legacy/deeper-notes/index.rst

@@ -0,0 +1,15 @@
+Deeper Notes
+============
+
+:date: 2026-01-05
+:category: Legacy
+:tags: rst, notes
+:authors: John Hu
+
+This post uses a folder layout.
+
+Images
+------
+
+.. image:: ./images/test.svg
+   :alt: Test image

package/content/series/rst-legacy/getting-started.rst

@@ -0,0 +1,24 @@
+Getting Started With rST
+========================
+
+:date: 2026-01-03
+:excerpt: A simple rST-based post inside a legacy series.
+:category: Legacy
+:tags: rst, migration
+:authors: John Hu
+:redirectFrom: /posts/getting-started-rst
+
+Intro paragraph with an inline link to `Amytis <https://github.com/hutusi/amytis>`_.
+
+Overview
+--------
+
+- Keep the routing layer unchanged.
+- Parse the source format at the series boundary.
+
+Code Sample
+~~~~~~~~~~~
+
+.. code-block:: ts
+
+  export const feature = "rst";

package/content/series/rst-legacy/index.rst

@@ -0,0 +1,9 @@
+Rst Legacy Series
+=================
+
+:excerpt: Legacy notes imported from reStructuredText.
+:authors: John Hu
+:sort: manual
+:posts: getting-started, deeper-notes
+
+This is a small legacy series used to validate series-scoped rST support.

package/content/series/rst-readme/README.rst

@@ -0,0 +1,9 @@
+Rst README Series
+=================
+
+:excerpt: Legacy series metadata loaded from README.rst.
+:authors: John Hu
+:sort: manual
+:posts: readme-index-post
+
+This series uses README.rst as its series index file.

package/content/series/rst-readme/readme-index-post.rst

@@ -0,0 +1,10 @@
+README Index Post
+=================
+
+:date: 2026-01-09
+:excerpt: Post inside a series whose metadata is loaded from README.rst.
+:category: Legacy
+:tags: rst, readme
+:authors: John Hu
+
+Content for the README-indexed series.

package/content/series/rst-toctree/first-post.rst

@@ -0,0 +1,6 @@
+First Post
+==========
+
+:date: 2024-01-01
+
+This post appears second in the toctree order.

package/content/series/rst-toctree/index.rst

@@ -0,0 +1,10 @@
+Rst Toctree Series
+==================
+
+:excerpt: Legacy series order derived from toctree.
+
+.. toctree::
+   :maxdepth: 1
+
+   second-post
+   first-post

package/content/series/rst-toctree/second-post.rst

@@ -0,0 +1,6 @@
+Second Post
+===========
+
+:date: 2024-01-02
+
+This post appears first in the toctree order.

package/content/series/rst-toctree-precedence/first-post.rst

@@ -0,0 +1,6 @@
+First Post
+==========
+
+:date: 2024-01-01
+
+This post should remain first because explicit posts metadata wins.

package/content/series/rst-toctree-precedence/index.rst

@@ -0,0 +1,12 @@
+Rst Toctree Precedence Series
+=============================
+
+:excerpt: Explicit posts metadata should override toctree order.
+:sort: manual
+:posts: first-post, second-post
+
+.. toctree::
+   :maxdepth: 1
+
+   second-post
+   first-post

package/content/series/rst-toctree-precedence/second-post.rst

@@ -0,0 +1,6 @@
+Second Post
+===========
+
+:date: 2024-01-02
+
+This post should remain second because explicit posts metadata wins.

package/docs/ARCHITECTURE.md

@@ -1,20 +1,21 @@
 # Architecture Overview
 
-Amytis is a static-export-first Next.js 16 App Router project for Markdown/MDX publishing across posts, series, books, flows, and notes.
+Amytis is a static-export-first Next.js 16 App Router project for Markdown/MDX publishing across posts, series, books, flows, and notes, with optional series-scoped rST support for legacy content.
 
 ## Core Stack
 
-- Framework: Next.js 16.1.6 + React 19
+- Framework: Next.js 16.2.1 + React 19
 - Runtime/tooling: Bun
 - Styling: Tailwind CSS v4 + CSS variables + `next-themes`
 - Content parsing: `gray-matter` + Zod validation in `src/lib/markdown.ts`
+- rST rendering: Python `docutils` bridge in `scripts/render-rst.py` plus normalization in `src/lib/rst-renderer.ts`
 - Search: Pagefind (`/pagefind/pagefind.js` loaded at runtime)
 - Tests: Bun test suites in `src/` and `tests/`
 
 ## Content Model
 
 - `content/posts/`: standalone posts (`.md/.mdx`) and folder posts (`index.mdx`)
-- `content/series/<slug>/`: series metadata (`index.mdx`) + series posts
+- `content/series/<slug>/`: series metadata (`index.mdx` / `index.md` / `README.mdx` / `README.md` / `index.rst` / `README.rst`) + series posts in the same format
 - `content/books/<slug>/`: book metadata + chapter files
 - `content/flows/YYYY/MM/DD.(md|mdx)`: daily flow entries
 - `content/notes/`: evergreen notes
@@ -27,6 +28,8 @@ Amytis is a static-export-first Next.js 16 App Router project for Markdown/MDX p
 3. Draft/future filtering and sorting are applied (based on `site.config.ts`).
 4. Route files consume typed helpers (`getAllPosts`, `getBookData`, `getAllFlows`, `getAllNotes`, etc.).
 5. `generateStaticParams()` precomputes dynamic routes for static export.
+6. Series content format is inferred from the series index file; ambiguous or mixed-format series fail fast during content loading.
+7. When `docutils` is available, rST files are rendered to HTML through the Python bridge; if the Python runtime is unavailable, Amytis falls back to the lightweight built-in rST compatibility path.
 
 ## Route Map (App Router)
 
@@ -57,7 +60,14 @@ src/app/
   authors/[author]/page.tsx
   archive/page.tsx
   graph/page.tsx
-  feed.xml/route.ts
+  feed.xml/route.ts                 # Main curated RSS feed
+  feed.atom/route.ts                # Main curated Atom feed
+  all.xml/route.ts                  # Firehose RSS feed
+  all.atom/route.ts                 # Firehose Atom feed
+  posts/feed.xml/route.ts           # Posts-only RSS feed
+  posts/feed.atom/route.ts          # Posts-only Atom feed
+  flows/feed.xml/route.ts           # Flows-only RSS feed
+  flows/feed.atom/route.ts          # Flows-only Atom feed
   search.json/route.ts
   sitemap.ts
   [slug]/page.tsx                   # Static pages + custom series listing path
@@ -68,10 +78,16 @@ src/app/
 ## URL Routing Rules
 
 - `next.config.ts` sets `output: "export"` and `trailingSlash: true`.
+- Series format is inferred from the index file:
+  - Markdown series: `index.md`, `index.mdx`, `README.md`, or `README.mdx`
+  - rST series: `index.rst` or `README.rst`
+- A series may not mix Markdown and rST content files; ambiguous or mixed layouts are treated as build errors.
 - Post URLs use `getPostUrl()` in `src/lib/urls.ts`:
   - Default: `/<posts.basePath>/<post.slug>` (basePath defaults to `posts`)
   - Series auto path: `/<series.slug>/<post.slug>` when `series.autoPaths` is enabled
   - Series override: `/<series.customPaths[seriesSlug]>/<post.slug>`
+- Legacy aliases declared in frontmatter `redirectFrom` are emitted as static redirect pages, so old URLs can continue resolving after a rename or path migration.
+- Dynamic route handlers validate whether a request is canonical or legacy, then either render the content or return `RedirectPage`.
 - Dynamic route params should return raw segment values from `generateStaticParams()` (do not pre-encode values).
 - Links should always target concrete paths, not route placeholders such as `/posts/[slug]`.
 - When moving series posts off the default posts path, `scripts/add-series-redirects.ts` updates frontmatter `redirectFrom` entries so static redirect pages can be generated.
@@ -92,6 +108,16 @@ src/app/
 - Notes: `getAllNotes`, `getNoteBySlug`, `getNotesByTag`
 - Discovery: `buildSlugRegistry`, `getBacklinks`, `getAllTags`, `getAllAuthors`
 
+## rST Notes
+
+- Full-fidelity rST rendering depends on a Python environment with `docutils` (and ideally `pygments`) available.
+- `src/lib/rst-renderer.ts` uses `AMYTIS_RST_PYTHON` when set; otherwise it falls back to `python3`.
+- Top-of-document docinfo is parsed into Amytis metadata, but it is stripped from rendered article HTML so blog-style posts do not show duplicate author/version blocks above the content.
+- Supported legacy roles are normalized or degraded intentionally:
+  - `:doc:` resolves to local site URLs when the target exists in the imported content tree
+  - `:ref:` / `:numref:` prefer local anchors
+  - unresolved legacy roles degrade to readable inline HTML instead of docutils system-message blocks
+
 ## Build Pipeline
 
 1. `bun scripts/copy-assets.ts`: copy co-located media into `public/`

package/docs/CONTRIBUTING.md

@@ -47,6 +47,17 @@ bun run new-flow
 bun run new-series "My Series Name"
 ```
 
+Series are format-scoped:
+
+- Markdown series use `content/series/<slug>/index.mdx` or `index.md`
+- Markdown series may also use `README.mdx` or `README.md`
+- rST series use `content/series/<slug>/index.rst` or `README.rst`
+- Child posts inside the series must use the same format as the index file
+- Mixed Markdown and rST files in one series are treated as build errors
+- For full-fidelity rST rendering, install `docutils` (and `pygments` for code highlighting) in a Python environment available to the project
+- If needed, set `AMYTIS_RST_PYTHON=/absolute/path/to/python` so Amytis uses a specific interpreter
+- Without Python/docutils, Amytis falls back to a lightweight compatibility parser; that keeps loading/building working, but some legacy rST constructs will render with lower fidelity
+
 ### Creating Books
 
 Books are manually structured in `content/books/`.

package/docs/DIGITAL_GARDEN.md

@@ -37,12 +37,33 @@ The `/graph` route visualizes your entire digital garden as an interactive netwo
 - **Edges**: Represent wiki-links connecting them.
 - **Interaction**: Click a node to navigate to that page.
 
-### 5. Flows (`/flows`)
+### 5. Collections (`/series`)
+While a "Series" is typically a linear progression of posts (e.g., Part 1, Part 2), a **Collection** allows you to manually curate an arbitrary list of posts and other series into a single grouped page.
+
+To create a collection, set `type: collection` in a series index file:
+
+- **Location:** `content/series/[collection-slug]/index.mdx`
+- **Frontmatter:**
+  ```yaml
+  ---
+  title: "Modern Web Development"
+  type: collection
+  items:
+    - post: posts/asynchronous-javascript  # Namespaced reference to a standalone post
+    - post: ai-nexus-weekly/week-11        # Namespaced reference to a post inside another series
+    - post: understanding-react-hooks      # Fallback reference (searches all posts by slug)
+    - series: nextjs-deep-dive             # Embeds all posts from another series
+  ---
+  ```
+Using a namespace (`folder/slug`) in the `post` definition prevents slug collisions and explicitly targets the exact file location.
+
+### 6. Flows (`/flows`)
 Flows are a stream-style collection of daily notes, micro-blogging, or imported chat logs. They are ideal for quick thoughts that don't necessarily warrant a full blog post.
 
 - **Location:** `content/flows/YYYY/MM/DD.mdx`
 - **Navigation:** Grouped by date in a timeline view.
 - **Importing:** Use `bun run new-flow-from-chat` to bring in external conversations.
+- **Optional Title:** Set `title` in frontmatter or use an `# Heading` in the content to display a title alongside the date.
 
 ## How to Use
 

package/eslint.config.mjs

@@ -16,6 +16,8 @@ const eslintConfig = defineConfig([
     "public/pagefind/**",
     // Package compiled output — not authored code
     "packages/*/dist/**",
+    // Local Python renderer virtualenv
+    ".venv-rst/**",
   ]),
 ]);
 

package/next.config.ts

@@ -15,8 +15,8 @@ const nextConfig: NextConfig = {
   output: "export",
   images: {
     loader: "custom",
-    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
-    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
+    imageSizes: [64, 128, 256],
+    deviceSizes: [640, 1200, 1920],
   },
   transpilePackages: ["next-image-export-optimizer"],
   env: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hutusi/amytis",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "A high-performance digital garden and blog engine with Next.js 16 and Tailwind CSS v4",
   "repository": {
     "type": "git",
@@ -11,14 +11,18 @@
   },
   "homepage": "https://github.com/hutusi/amytis#readme",
   "private": false,
-  "packageManager": "bun@1.3.4",
+  "packageManager": "bun@1.3.11",
   "scripts": {
-    "dev": "next dev",
-    "build": "bun scripts/copy-assets.ts && bun run build:graph && next build && next-image-export-optimizer && pagefind --site out",
-    "build:dev": "bun scripts/copy-assets.ts && bun run build:graph && next build && pagefind --site out --output-path public/pagefind",
+    "dev": "bun scripts/run-with-rst-python.ts next dev",
+    "build": "bun scripts/copy-assets.ts && bun run build:graph && bun scripts/run-with-rst-python.ts next build && next-image-export-optimizer && bun run build:search",
+    "build:dev": "bun scripts/copy-assets.ts && bun run build:graph && bun scripts/run-with-rst-python.ts next build && bun run build:search:dev",
     "build:graph": "NODE_ENV=production bun scripts/generate-knowledge-graph.ts",
+    "build:search": "bun scripts/build-pagefind.ts --site out --output-path out/pagefind",
+    "build:search:dev": "bun scripts/build-pagefind.ts --site out --output-path public/pagefind",
+    "build:search:cli": "pagefind --site out",
+    "build:search:cli:dev": "pagefind --site out --output-path public/pagefind",
     "validate": "bun run lint && bun run test && bun run build:dev",
-    "clean": "rm -rf .next out public/posts public/books public/flows",
+    "clean": "rm -rf .next out public/posts public/books public/flows public/images/nextImageExportOptimizer",
     "new": "bun scripts/new-post.ts",
     "new-weekly": "bun scripts/new-post.ts --series ai-nexus-weekly --md --folder --prefix weekly",
     "new-series": "bun scripts/new-series.ts",
@@ -48,16 +52,16 @@
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
     "image-size": "^2.0.2",
-    "katex": "^0.16.33",
-    "mermaid": "^11.12.3",
-    "next": "16.1.6",
+    "katex": "^0.16.45",
+    "mermaid": "^11.14.0",
+    "next": "16.2.3",
     "next-image-export-optimizer": "^1.20.1",
     "next-themes": "^0.4.6",
-    "react": "19.2.4",
-    "react-dom": "19.2.4",
-    "react-icons": "^5.5.0",
+    "react": "19.2.5",
+    "react-dom": "19.2.5",
+    "react-icons": "^5.6.0",
     "react-markdown": "^10.1.0",
-    "react-syntax-highlighter": "^16.1.0",
+    "react-syntax-highlighter": "^16.1.1",
     "rehype-katex": "^7.0.1",
     "rehype-raw": "^7.0.0",
     "rehype-slug": "^6.0.0",
@@ -66,28 +70,30 @@
     "remark-math": "^6.0.0",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
+    "sanitize-html": "^2.17.2",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@playwright/test": "^1.58.2",
-    "@tailwindcss/postcss": "^4.1.18",
-    "@types/bun": "^1.3.9",
+    "@playwright/test": "^1.59.1",
+    "@tailwindcss/postcss": "^4.2.2",
+    "@types/bun": "^1.3.12",
     "@types/d3": "^7.4.3",
     "@types/hast": "^3.0.4",
     "@types/image-size": "^0.8.0",
     "@types/mdast": "^4.0.4",
-    "@types/node": "^24.10.13",
+    "@types/node": "^24.12.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@types/react-syntax-highlighter": "^15.5.13",
+    "@types/sanitize-html": "^2.16.1",
     "babel-plugin-react-compiler": "1.0.0",
-    "eslint": "^9.0.0",
-    "eslint-config-next": "16.1.6",
-    "pagefind": "^1.4.0",
+    "eslint": "^9.39.4",
+    "eslint-config-next": "16.2.3",
+    "pagefind": "^1.5.0",
     "pdf-to-img": "^5.0.0",
-    "tailwindcss": "^4.1.18",
+    "tailwindcss": "^4.2.2",
     "typescript": "^5.9.3"
   },
   "ignoreScripts": [

package/packages/create-amytis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-amytis",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Create a new Amytis digital garden",
   "license": "MIT",
   "bin": { "create-amytis": "./dist/index.js" },

package/packages/create-amytis/src/index.test.ts

@@ -2,7 +2,7 @@ import { describe, test, expect, afterAll } from "bun:test";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
-import { patchSiteConfig, patchPackageJson } from "./index";
+import { buildExtractCommand, getArchiveMetadata, patchSiteConfig, patchPackageJson } from "./index";
 
 // Minimal site.config.ts that mirrors the real file's patchable fields.
 // Inner backticks and `${` are escaped so they appear literally in the string.
@@ -185,3 +185,45 @@ describe("patchPackageJson", () => {
     expect(() => patchPackageJson(dir, "my-garden")).not.toThrow();
   });
 });
+
+describe("getArchiveMetadata", () => {
+  test("uses zip archives on Windows", () => {
+    const archive = getArchiveMetadata("v1.13.0", "win32");
+    expect(archive.kind).toBe("zip");
+    expect(archive.filename).toBe("amytis-v1.13.0.zip");
+    expect(archive.url).toBe("https://github.com/hutusi/amytis/archive/refs/tags/v1.13.0.zip");
+  });
+
+  test("uses tar.gz archives on non-Windows platforms", () => {
+    const archive = getArchiveMetadata("v1.13.0", "darwin");
+    expect(archive.kind).toBe("tar.gz");
+    expect(archive.filename).toBe("amytis-v1.13.0.tar.gz");
+    expect(archive.url).toBe("https://github.com/hutusi/amytis/archive/refs/tags/v1.13.0.tar.gz");
+  });
+});
+
+describe("buildExtractCommand", () => {
+  test("builds the PowerShell Expand-Archive command on Windows", () => {
+    const command = buildExtractCommand("C:\\tmp\\amytis-v1.13.0.zip", "C:\\tmp\\my-garden.__tmp__", "zip", "win32");
+    expect(command.command).toBe("powershell.exe");
+    expect(command.args).toEqual([
+      "-NoProfile",
+      "-NonInteractive",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-Command",
+      "Expand-Archive",
+      "-LiteralPath",
+      "C:\\tmp\\amytis-v1.13.0.zip",
+      "-DestinationPath",
+      "C:\\tmp\\my-garden.__tmp__",
+      "-Force",
+    ]);
+  });
+
+  test("builds the tar extraction command on non-Windows platforms", () => {
+    const command = buildExtractCommand("/tmp/amytis-v1.13.0.tar.gz", "/tmp/my-garden.__tmp__", "tar.gz", "darwin");
+    expect(command.command).toBe("tar");
+    expect(command.args).toEqual(["xzf", "/tmp/amytis-v1.13.0.tar.gz", "-C", "/tmp/my-garden.__tmp__"]);
+  });
+});

package/packages/create-amytis/src/index.ts

@@ -4,7 +4,7 @@ import * as fs from "fs";
 import * as path from "path";
 import * as https from "https";
 import * as readline from "readline";
-import { execSync } from "child_process";
+import { execFileSync, execSync } from "child_process";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -77,11 +77,67 @@ function downloadFile(url: string, dest: string): Promise<void> {
   });
 }
 
-function extractTarball(tarPath: string, outDir: string): void {
+export function getArchiveMetadata(tag: string, platform: NodeJS.Platform = process.platform): {
+  url: string;
+  filename: string;
+  kind: "zip" | "tar.gz";
+} {
+  if (platform === "win32") {
+    return {
+      url: `https://github.com/hutusi/amytis/archive/refs/tags/${tag}.zip`,
+      filename: `amytis-${tag}.zip`,
+      kind: "zip",
+    };
+  }
+
+  return {
+    url: `https://github.com/hutusi/amytis/archive/refs/tags/${tag}.tar.gz`,
+    filename: `amytis-${tag}.tar.gz`,
+    kind: "tar.gz",
+  };
+}
+
+export function buildExtractCommand(
+  archivePath: string,
+  tmpDir: string,
+  kind: "zip" | "tar.gz",
+  platform: NodeJS.Platform = process.platform,
+): { command: string; args: string[] } {
+  if (kind === "zip") {
+    if (platform !== "win32") {
+      throw new Error("ZIP extraction is only supported on Windows in create-amytis");
+    }
+
+    return {
+      command: "powershell.exe",
+      args: [
+        "-NoProfile",
+        "-NonInteractive",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-Command",
+        "Expand-Archive",
+        "-LiteralPath",
+        archivePath,
+        "-DestinationPath",
+        tmpDir,
+        "-Force",
+      ],
+    };
+  }
+
+  return {
+    command: "tar",
+    args: ["xzf", archivePath, "-C", tmpDir],
+  };
+}
+
+function extractArchive(archivePath: string, outDir: string, kind: "zip" | "tar.gz", platform: NodeJS.Platform = process.platform): void {
   // Extract into a temp dir, then move the inner folder out
   const tmpDir = `${outDir}.__tmp__`;
   fs.mkdirSync(tmpDir, { recursive: true });
-  execSync(`tar xzf "${tarPath}" -C "${tmpDir}"`);
+  const { command, args } = buildExtractCommand(archivePath, tmpDir, kind, platform);
+  execFileSync(command, args, { stdio: "inherit" });
 
   // The tarball unpacks to a single top-level dir like "amytis-1.2.0/"
   const entries = fs.readdirSync(tmpDir);
@@ -91,7 +147,7 @@ function extractTarball(tarPath: string, outDir: string): void {
   const innerDir = path.join(tmpDir, entries[0]);
   fs.renameSync(innerDir, outDir);
   fs.rmdirSync(tmpDir);
-  fs.unlinkSync(tarPath);
+  fs.unlinkSync(archivePath);
 }
 
 // ---------------------------------------------------------------------------
@@ -180,14 +236,14 @@ async function main(): Promise<void> {
   console.log(`  Found: ${tag}`);
 
   // 3. Download tarball
-  const tarUrl = `https://github.com/hutusi/amytis/archive/refs/tags/${tag}.tar.gz`;
-  const tarDest = path.join(process.cwd(), `amytis-${tag}.tar.gz`);
+  const archive = getArchiveMetadata(tag);
+  const archiveDest = path.join(process.cwd(), archive.filename);
   console.log("Downloading tarball...");
-  await downloadFile(tarUrl, tarDest);
+  await downloadFile(archive.url, archiveDest);
 
   // 4. Extract
   console.log("Extracting...");
-  extractTarball(tarDest, targetDir);
+  extractArchive(archiveDest, targetDir, archive.kind);
   console.log(`  Scaffolded: ${targetDir}`);
 
   // 5-6. Prompt for site metadata