1 files changed, 755 insertions, 0 deletions
diff --git a/doc/Specifications.md b/doc/Specifications.md
new file mode 100644
index 0000000..d2e9157
--- /dev/null
+++ b/doc/Specifications.md
@@ -0,0 +1,755 @@
+はい。公式ドキュメントに沿って見直すと、前回の要求仕様にはいくつか **Zola固有の構成・命名に寄せた方がよい点**があります。
+
+特に重要なのは、Zolaは公式に「サイト構造を決めつけない」としており、基本は `content/` 配下の **Section (`_index.md`) と Page (`*.md`)**、そして `template` / `page_template` でテンプレートを結びつける構造です。公式の初期ディレクトリも `zola.toml / content / sass / static / templates / themes` です。 ([Zola][1])
+
+その前提で、Codex向け仕様は次のように修正するのがよいです。
+
+````markdown
+# Zola Web Site Client Implementation Requirements
+
+## 1. 目的
+
+自前VPS上で Caddy により配信する個人Webサイトを Zola で構築する。
+
+本番VPSでは動的Webアプリケーションを実行せず、クライアントPC上で Zola により静的HTML/CSS/JSを生成し、生成済み成果物のみをVPSへデプロイする。
+
+npm / Node.js に依存しない構成とし、Webサイト構築に伴うサプライチェーン攻撃面を最小化する。
+
+---
+
+# 2. Zola採用方針
+
+Zola公式ドキュメントの構造・概念・標準機能に従うこと。
+
+Zolaは以下を基本概念として使用する。
+
+- Site configuration: `zola.toml`
+- Content
+  - Section: `_index.md`
+  - Page: 通常のMarkdownファイル
+- Templates: Tera
+- Sass: `sass/`
+- Static assets: `static/`
+- Themes: `themes/`
+- Build output: `public/`
+
+独自のディレクトリ規約や別SSG由来の設計を持ち込まず、Zola標準のSection/Pageモデルを優先する。
+
+---
+
+# 3. 必須技術構成
+
+| 領域 | 採用 |
+|---|---|
+| Static Site Generator | Zola |
+| Configuration | `zola.toml` |
+| Content | CommonMark Markdown |
+| Content model | Zola Section / Page |
+| Template engine | Tera |
+| Style | Sass / SCSS |
+| JavaScript | 必要最小限の vanilla JavaScript |
+| Backend | なし |
+| Database | なし |
+| npm / Node.js | 使用しない |
+| htmx | 使用しない |
+| External CDN | 原則使用しない |
+| Production Web server | Caddy |
+
+---
+
+# 4. Zola標準ディレクトリ構造
+
+`zola init` が生成する構造を基準とする。
+
+```text
+website/
+├── zola.toml
+├── content/
+├── sass/
+├── static/
+├── templates/
+└── themes/
+````
+
+build後には以下が生成される。
+
+```text
+public/
+```
+
+`public/` は生成物でありGit管理しない。
+
+`themes/` はZola標準ディレクトリとして保持してよいが、本プロジェクトでは外部themeを原則使用しない。
+
+---
+
+# 5. 初期サイト構造
+
+以下のコンテンツ領域を実装する。
+
+```text
+/
+├── about/
+├── projects/
+└── notes/
+```
+
+想定URL:
+
+```text
+https://www.takashi-2521.com/
+https://www.takashi-2521.com/about/
+https://www.takashi-2521.com/projects/
+https://www.takashi-2521.com/notes/
+```
+
+ZolaのSection/Pageモデルに従い、以下を基本構造とする。
+
+```text
+content/
+├── about.md
+│
+├── projects/
+│   ├── _index.md
+│   ├── project-a.md
+│   └── project-b.md
+│
+└── notes/
+    ├── _index.md
+    ├── note-a.md
+    └── note-b.md
+```
+
+`projects/_index.md` と `notes/_index.md` は Zola Section とする。
+
+`projects/*.md` および `notes/*.md` は Zola Page とする。
+
+About は単独Pageとして扱う。
+
+必要な理由がある場合のみPage Bundle等の別構造を採用してよい。
+
+---
+
+# 6. Section設計
+
+## 6.1 Projects Section
+
+`content/projects/_index.md` を作成する。
+
+例:
+
+```toml
++++
+title = "Projects"
+sort_by = "date"
+template = "projects.html"
+page_template = "project-page.html"
++++
+```
+
+Zola標準のSection変数を使用する。
+
+Projects一覧はTera側で、
+
+```text
+section.pages
+```
+
+を利用して生成する。
+
+独自JSON index等を作成しない。
+
+---
+
+## 6.2 Notes Section
+
+`content/notes/_index.md` を作成する。
+
+例:
+
+```toml
++++
+title = "Notes"
+sort_by = "date"
+template = "notes.html"
+page_template = "note-page.html"
++++
+```
+
+新しいNoteは `content/notes/*.md` を追加するだけで一覧へ反映されること。
+
+---
+
+# 7. Page設計
+
+## 7.1 Project Page
+
+Projectは1 Markdown = 1 Zola Pageとする。
+
+例:
+
+```toml
++++
+title = "Example Project"
+date = 2026-08-21
+description = "Project description"
+
+[extra]
+status = "active"
+repository = "https://example.invalid/"
++++
+```
+
+Zola標準front matterで直接扱えないプロジェクト固有metadataは `[extra]` を使用する。
+
+最低限以下を扱えるようにする。
+
+* `title`
+* `date`
+* `description`
+
+Project固有情報:
+
+* `extra.status`
+* `extra.repository`
+
+必要なら以下も追加可能。
+
+* `extra.homepage`
+* `extra.language`
+* `extra.license`
+
+metadataを過剰に増やさないこと。
+
+---
+
+## 7.2 Note Page
+
+例:
+
+```toml
++++
+title = "Example Note"
+date = 2026-08-21
+description = "Note description"
++++
+
+本文...
+```
+
+本文はZolaの `page.content` としてtemplateから表示する。
+
+---
+
+# 8. Templates
+
+Zola公式ドキュメントのtemplate inheritanceを利用する。
+
+最低限以下を構成する。
+
+```text
+templates/
+├── base.html
+├── index.html
+├── projects.html
+├── project-page.html
+├── notes.html
+├── note-page.html
+└── page.html
+```
+
+必要であれば以下を追加する。
+
+```text
+templates/
+└── partials/
+    ├── header.html
+    ├── navigation.html
+    └── footer.html
+```
+
+`base.html` を共通レイアウトとし、各templateはTeraの
+
+```text
+{% extends "base.html" %}
+```
+
+およびblockを使用する。
+
+---
+
+# 9. Internal Link方針
+
+サイト内部リンクは、可能な限りURL文字列をハードコードせず、Zolaの `get_url` と `@/` internal link記法を使用する。
+
+例:
+
+```tera
+<a href="{{ get_url(path='@/projects/_index.md') }}">Projects</a>
+```
+
+これによりcontent path変更時のリンク破損を減らす。
+
+---
+
+# 10. Home Page
+
+Homeは `templates/index.html` で生成する。
+
+最低限以下を表示可能にする。
+
+* サイト名
+* 簡単な説明
+* Aboutへのリンク
+* Projectsへのリンク
+* Notesへのリンク
+
+Home用の不要なCMS的データ構造は作らない。
+
+必要なら `zola.toml` の `extra` をサイト全体metadataとして使用してよい。
+
+---
+
+# 11. Sass / SCSS
+
+Zola標準Sass compilationを使用する。
+
+`zola.toml`:
+
+```toml
+compile_sass = true
+```
+
+構成例:
+
+```text
+sass/
+├── main.scss
+├── _variables.scss
+├── _base.scss
+├── _typography.scss
+├── _layout.scss
+└── _components.scss
+```
+
+npm Sass / Dart Sass / PostCSS等は追加しない。
+
+---
+
+# 12. Static assets
+
+Zolaの `static/` はbuild時に出力先へそのままコピーされる前提で使用する。
+
+例:
+
+```text
+static/
+├── favicon.svg
+├── robots.txt
+├── images/
+└── js/
+    └── site.js
+```
+
+外部CDN依存を原則禁止する。
+
+JavaScriptが必要な場合は `static/js/site.js` 等として自前配信する。
+
+---
+
+# 13. JavaScript
+
+JavaScriptは必要最小限の vanilla JavaScript のみ使用する。
+
+以下の原則に従う。
+
+1. HTML標準機能で実現可能ならJSを使用しない。
+2. CSSのみで実現可能ならJSを使用しない。
+3. 外部frontend frameworkを導入しない。
+4. inline event handlerを使用しない。
+5. `eval()` を使用しない。
+6. JavaScript無効でも主要コンテンツを閲覧可能にする。
+
+---
+
+# 14. Syntax Highlighting
+
+技術記事用のコードブロックsyntax highlightingにはZola標準機能を使用する。
+
+独自のPrism.js / highlight.js等は初期実装では導入しない。
+
+設定は採用するZola versionの公式configuration仕様に従うこと。
+
+---
+
+# 15. Feeds
+
+NotesについてRSS/Atom等のfeedを生成する。
+
+Zola標準feed生成機能を使用する。
+
+独自feed generatorは実装しない。
+
+採用するZola versionにおける推奨設定を確認して実装すること。
+
+---
+
+# 16. Sitemap
+
+Zola標準のsitemap生成機能を使用する。
+
+独自 `sitemap.xml` generatorは作らない。
+
+---
+
+# 17. robots.txt
+
+Zolaの標準 `robots.txt` template機能または `static/robots.txt` のうち、公式ドキュメントに沿った単純な方法を採用する。
+
+不要な独自処理を作らない。
+
+---
+
+# 18. 404 Page
+
+Zola標準の404 template仕様に従って実装する。
+
+想定:
+
+```text
+templates/404.html
+```
+
+Caddyから静的404として扱える成果物を生成する。
+
+---
+
+# 19. Search
+
+初期実装では検索を無効とする。
+
+`zola init` / configuration上もsearch indexを生成しない設定とする。
+
+将来必要になった場合のみZola標準search indexを再検討する。
+
+外部検索libraryは現時点では導入しない。
+
+---
+
+# 20. Themes
+
+Zolaは `themes/` を標準で持つが、本プロジェクトでは外部themeを原則使用しない。
+
+理由:
+
+* supply-chain面積を増やさない
+* upstream theme更新への依存を避ける
+* CSS/templateを完全に管理可能にする
+* 不要なJavaScriptを取り込まない
+
+したがって自前template + 自前SCSSを基本とする。
+
+---
+
+# 21. Zola Configuration
+
+設定ファイル名は公式構成に合わせて、
+
+```text
+zola.toml
+```
+
+を使用する。
+
+最低限:
+
+```toml
+base_url = "https://www.takashi-2521.com"
+compile_sass = true
+build_search_index = false
+```
+
+実際のsyntax highlighting、feed、taxonomy等については、使用するZola versionの公式documentationを確認して正しいconfiguration keyを使用すること。
+
+推測で設定名を追加しないこと。
+
+---
+
+# 22. Development
+
+ローカル開発ではZola標準development serverを使用する。
+
+```bash
+zola serve
+```
+
+Zolaは `zola.toml`, `content`, `sass`, `static`, `templates` の変更を監視し、local live reloadに使用できる。
+
+追加のdev serverは作成しない。
+
+---
+
+# 23. Validation / Build
+
+実装中は以下を使用する。
+
+```bash
+zola check
+zola build
+```
+
+local preview:
+
+```bash
+zola serve
+```
+
+build output:
+
+```text
+public/
+```
+
+`public/` のみでサイトが成立すること。
+
+---
+
+# 24. Git
+
+sourceのみGit管理する。
+
+`.gitignore`:
+
+```gitignore
+/public/
+```
+
+Zolaが実際に生成しない独自cache directoryを推測で追加しないこと。
+
+Editor / OS固有ファイルは必要に応じて追加可能。
+
+---
+
+# 25. Deployment境界
+
+本仕様ではVPS側の配信基盤は変更しない。
+
+既存:
+
+```text
+/srv/www/takashi-2521.com/
+├── releases/
+└── current -> releases/<release-id>
+```
+
+Caddy:
+
+```text
+root * /srv/www/takashi-2521.com/current
+```
+
+クライアント側では将来、
+
+```text
+zola check
+→ zola build
+→ public/
+→ archive
+→ SSH transfer
+→ releases/<release-id>
+→ current切替
+```
+
+を行う。
+
+本Client Phaseでは `public/` が自己完結したbuild artifactになることを保証する。
+
+---
+
+# 26. Security Requirements
+
+必須:
+
+* npmを使用しない
+* Node.js dependencyを使用しない
+* React/Vue/Svelteを使用しない
+* htmxを使用しない
+* Tailwindを使用しない
+* 外部CDNを使用しない
+* external themeを原則使用しない
+* backendを実装しない
+* DBを使用しない
+* buildをVPSで実行しない
+
+可能な限り以下のCSPと互換な構造にする。
+
+```text
+default-src 'self';
+script-src 'self';
+style-src 'self';
+img-src 'self' data:;
+font-src 'self';
+object-src 'none';
+base-uri 'self';
+frame-ancestors 'none';
+```
+
+inline script / inline event handlerは避ける。
+
+---
+
+# 27. Accessibility
+
+最低限以下を満たす。
+
+* semantic HTML
+* 正しいheading hierarchy
+* keyboard navigation
+* visible focus
+* alt text
+* color contrast
+* `prefers-reduced-motion` を考慮
+* JSなしでも主要navigationが利用可能
+
+---
+
+# 28. Client Phase
+
+## Client-1: Zola initialization
+
+* Zola version確認
+* `zola init` 相当の標準構成を確認
+* `zola.toml`
+* 標準directory作成
+* `zola check`
+* `zola build`
+
+PASS:
+
+```text
+zola check PASS
+zola build PASS
+public/index.html exists
+```
+
+---
+
+## Client-2: Section / Page architecture
+
+* Home
+* About Page
+* Projects Section
+* Project Pages
+* Notes Section
+* Note Pages
+
+PASS:
+
+```text
+/
+ /about/
+ /projects/
+ /projects/<page>/
+ /notes/
+ /notes/<page>/
+```
+
+が生成される。
+
+---
+
+## Client-3: Tera templates / UI
+
+* `base.html`
+* template inheritance
+* navigation
+* header/footer
+* SCSS
+* responsive layout
+
+PASS:
+
+* Desktop正常
+* Mobile正常
+* internal navigation正常
+
+---
+
+## Client-4: Content model
+
+Projects/NotesをZola Pageとして管理する。
+
+PASS:
+
+Markdownを1件追加すると、
+
+```text
+Section listing
++
+individual Page
+```
+
+の両方へ自動反映される。
+
+---
+
+## Client-5: Zola static features
+
+* syntax highlighting
+* feed
+* sitemap
+* robots.txt
+* 404
+* favicon
+
+Zola標準機能を優先する。
+
+PASS:
+
+`zola build` の成果物に必要な静的ファイルが生成される。
+
+---
+
+## Client-6: Git / final validation
+
+* `.gitignore`
+* sourceのみGit管理
+* external dependenciesなし
+* final `zola check`
+* final `zola build`
+
+---
+
+# 29. Final Acceptance Criteria
+
+以下をすべて満たすこと。
+
+* [ ] Zola公式のSection/Pageモデルを使用している
+* [ ] `zola.toml` を使用している
+* [ ] `content/` を使用している
+* [ ] Sectionは `_index.md` で定義されている
+* [ ] ProjectはZola Pageとして実装されている
+* [ ] NoteはZola Pageとして実装されている
+* [ ] Section `template` / `page_template` を適切に使用している
+* [ ] Tera template inheritanceを使用している
+* [ ] internal linkにZola標準機能を利用している
+* [ ] Sass compilationはZola標準機能
+* [ ] syntax highlightingはZola標準機能
+* [ ] feedはZola標準機能
+* [ ] sitemapはZola標準機能
+* [ ] 404はZola標準機能
+* [ ] `zola serve` が動作
+* [ ] `zola check` が成功
+* [ ] `zola build` が成功
+* [ ] `public/` 単独で静的サイトとして成立
+* [ ] npm dependencyなし
+* [ ] Node.js dependencyなし
+* [ ] frontend frameworkなし
+* [ ] htmxなし
+* [ ] external CDNなし
+* [ ] external theme依存なし
+* [ ] backendなし
+* [ ] DBなし
+* [ ] `public/` はGit管理外
+
+[1]: https://www.getzola.org/documentation/getting-started/overview/ "Overview | Zola"