手順、レシピ、チェックリスト、ランブックを一つの社内参照構造として扱う

あなたは Codex。Cloudflare 上で「社内マニュアル魔法 / Internal Manual Spell」という production-shaped prototype を構築せよ。

あなたの仕事は concept page を書くことではない。business procedures、recipes、operating instructions、cautions、prerequisites、revision history を一つの unified manual structure として扱う、実際に動く internal manual system prototype を実装することだ。

高い自律性を持つ non-interactive なスタイルで進めること。
確認質問はしないこと。
妥当な前提を自分で置き、コード、コメント、型安全性、バリデーション、deployability を備えた完全な prototype を end-to-end で実装すること。

Project goal

operational procedures、recipes、SOPs、checklists、workstation instructions、service flows、cleaning routines、opening / closing tasks などに再利用できる internal manual system を構築する。

このシステムは次を支える必要がある:
1. structured manual content
2. step-by-step procedure rendering
3. recipe-style and operation-style document types
4. role-based access control
5. revision awareness
6. search
7. operation flow / reading order
8. recent updates visibility
9. staff-only portal capability
10. admin metadata and revision inspection
11. print-friendly and mobile-friendly reading
12. content sync from repository-based source files

Core product concept

procedures、recipes、operations を一つの親 manual structure として扱う。

このシステムは次を理解しやすくしなければならない:
- 何をするか
- どの順番で進めるか
- 何の tools や materials が必要か
- どんな cautions があるか
- 誰が読むべきか
- current version は何か
- 最近何が変わったか

これは単なる general knowledge base ではない。
operational sequence、required items、warnings、version control を first-class に持つ structured internal manual foundation である。

必要に応じてコードコメントや命名では次の framing を使ってよい:
- Procedure Familiar = steps、prerequisites、tools、materials、cautions、checks を構造化する
- Access Familiar = 誰が何を読めるかを制御する
- Revision Familiar = version flow を保持し、古い instructions が気づかれないまま残ることを防ぐ

将来的には次へ接続できる設計にする:
- training portals
- onboarding flows
- sign-off / read acknowledgement flows
- restricted departmental manuals
- policy distribution
- incident response runbooks

Non-goals for this prototype

full CMS は作らない。
collaborative rich-text editor は作らない。
full HR training compliance tracking は作らない。
e-signature workflows は作らない。
video hosting を required dependency にしない。
permissions は practical な staff / admin model with role-aware filtering を超えて複雑化しない。

Fixed stack

絶対に不可能でない限り、次の stack をそのまま使う:
- Frontend: Astro + TypeScript
- Interactive UI where needed: minimal React islands
- Content source: repository 内の Markdown or MDX files
- Backend / API: Cloudflare Pages Functions または Cloudflare Workers。最も単純な Cloudflare-native route を選ぶ
- Database: Cloudflare D1
- Auth: Cloudflare Access compatible staff gate
- Search: metadata と step text の軽量な server-side search index
- Validation: Zod
- Testing: Vitest at minimum
- Styling: clean CSS, content-first, no UI library required

Architecture

次のような repository layout を使う:
- apps/web = Astro frontend と admin UI
- content/manuals = Markdown or MDX source files
- packages/shared = shared types、validation schemas、content parsing、search、access logic、revision logic

より単純な構成を選ぶ場合でも、次は明確に分離すること:
- manual source content
- content sync and parsing
- metadata / revision logic
- access control
- search
- frontend rendering
- admin inspection views

Functional requirements

1. Structured manual types

少なくとも次の manual content types を支える:
- procedure
- recipe
- checklist
- runbook
- troubleshooting

各 manual document は少なくとも次の metadata を持てること:
- title
- slug
- summary
- manual type
- section
- chapter optional
- visibility
- status
- version label
- tags
- audience label optional
- estimated time optional
- prerequisites optional
- tools optional
- materials or ingredients optional
- related documents optional
- reading order optional
- operation flow key optional
- updated at timestamp

2. Step-based procedure structure

各 manual は clearly structured steps を持てること。

各 step は次を持てる:
- step number
- title optional
- instruction text
- duration minutes optional
- caution text optional
- quality check or success condition optional
- note optional

この構造は UI で明確に render されなければならない。
procedure を unstructured block text に落としてはならない。

3. Recipe and operation structure

recipe-style manuals は次を見せられること:
- ingredients or materials
- quantity text
- yield or batch note optional
- preparation notes
- ordered steps

operation-style manuals は次を見せられること:
- prerequisites
- tools
- opening / closing or execution sequence
- checkpoints
- failure or troubleshooting notes

4. Role-based access control

internal manuals に適した access control を実装する。

少なくとも次を支える:
- staff
- manager
- admin

必要なら public や authenticated も持ってよいが、基本は internal staff documentation を前提にする。

access control は次すべてに適用する:
- page rendering
- API responses
- search results
- navigation lists
- update feeds

保護対象 manual の metadata を unauthorized users に漏らしてはならない。

5. Revision and update model

revision-aware structure を実装する。

各 manual は次を支える:
- one canonical current version
- revision metadata
- updated_at timestamp
- changelog summary optional
- revision history in D1

prototype では:
- manual source は Markdown or MDX
- metadata と revision records は D1
- UI で last updated と version を表示する
- recent updates feed を見せる

in-browser editor は不要だが、content maintenance flow は明確で実在していなければならない。

6. Search

accessible manual content に対する working search を実装する。

search は少なくとも次を支える:
- title
- summary
- tags
- section
- manual type
- step text
- caution text where practical

search results は:
- access control を尊重する
- manual pages へリンクする
- manual type と updated date を見せる
- practical なら type や section filtering を支える

7. Operation flow / ordered navigation

operation flow または ordered manual sequence を実装する。

少なくとも:
- manuals can belong to an operation flow
- manuals can have sequence numbers inside a flow
- UI can show previous and next manual
- UI can show “start here” for a flow

例として少なくとも 1 つ operation flow を用意する:
- Opening Shift Flow
または
- Daily Kitchen Prep Flow

8. Manual page experience

各 manual page は少なくとも次を明確に見せる:
- title
- summary
- manual type
- version
- last updated
- section or chapter
- audience or visibility label where appropriate
- prerequisites
- tools or ingredients where appropriate
- numbered steps
- cautions
- related manuals
- previous / next links when part of a flow

さらに次も支える:
- print-friendly layout
- compact mobile reading
- optional checklist mode with local state only

checklist mode は client-side local state でよく、server persistence は不要。

9. Recent updates visibility

updates feed では次を見せる:
- recently changed manuals
- version label
- update date
- changelog summary where available

これにより、古い instructions が静かに残り続けることを防ぐ。

10. Admin / staff inspection view

staff-only admin area では次を見られること:
- manuals list
- type / visibility / section / status filtering
- manual metadata
- step structure
- revision history
- recent update events
- operation flow structure
- manual content sync trigger

CMS を過剰に作り込まないこと。operational で readable に留める。

11. Content sync from repository

content sync flow は次を行う:
- content directory から Markdown or MDX files を読む
- frontmatter と step structure を Zod で validate する
- metadata を D1 に insert / update する
- source content が変わったとき new revision records を作る
- search index data を refresh する

sync は deterministic で、手順を documented にすること。

12. Future readiness

将来次を支えられるように設計する:
- read acknowledgement
- departmental targeting
- media attachments
- import from external source repositories
- scheduled sync jobs
- richer identity provider integration

今すべてを実装する必要はないが、構造がそれを妨げてはならない。

Data model

少なくとも次の tables を D1 schema として実装する:

manual_documents
- id
- slug
- title
- summary
- manual_type
- section_key
- chapter_key nullable
- visibility
- status
- version_label
- audience_label nullable
- source_path
- tags_json
- prerequisites_json nullable
- tools_json nullable
- materials_json nullable
- yield_text nullable
- estimated_minutes nullable
- reading_order nullable
- operation_flow_key nullable
- current_revision_id nullable
- created_at
- updated_at

manual_steps
- id
- manual_document_id
- step_number
- title nullable
- instruction_markdown
- duration_minutes nullable
- caution_text nullable
- quality_check_text nullable
- note_text nullable
- created_at
- updated_at

manual_revisions
- id
- manual_document_id
- revision_number
- version_label
- source_hash
- changelog_summary nullable
- rendered_excerpt nullable
- created_at
- created_by nullable

operation_flows
- id
- flow_key
- title
- description
- visibility
- created_at
- updated_at

operation_flow_items
- id
- operation_flow_id
- manual_document_id
- sequence_number
- created_at

update_events
- id
- manual_document_id
- revision_id
- event_type
- payload_json
- created_at

search_index は implementation practicality が明確な場合のみ追加してよい。
first prototype を unnecessary に肥大化させないこと。

Content source model

manual source は Markdown or MDX files with frontmatter として保存する。

frontmatter は少なくとも次を支える:
- title
- slug
- summary
- manualType
- section
- chapter
- visibility
- status
- version
- updatedAt
- tags
- audience
- estimatedMinutes
- prerequisites
- tools
- materials
- yieldText
- operationFlow
- flowOrder
- changelogSummary

source file は structured step data も支えること。
最も単純で robust な path を選ぶ。たとえば:
- YAML frontmatter の steps array of objects
または
- MDX components for steps

content model は Zod で validate すること。

Security

safe practices を実装する:
- content metadata を Zod で validate
- API input を validate
- staff / admin routes を auth middleware stub で保護
- protected manuals を search / navigation / update feeds 経由で漏らさない
- search input を sanitize
- useful だが oversharing しない error messages を返す

API design

次に近い JSON endpoints を実装する:

User-facing:
GET /api/manuals/navigation
GET /api/manuals/search?q=...
GET /api/manuals/:slug
GET /api/manuals/updates
GET /api/flows
GET /api/flows/:flowKey

Admin:
GET /api/admin/manuals
GET /api/admin/manuals/:slug
GET /api/admin/revisions/:slug
GET /api/admin/flows
GET /api/admin/access-summary
GET /api/admin/update-events
POST /api/admin/sync-content

命名は調整してよいが、この能力は保持すること。

Frontend pages

少なくとも次の pages を構築する:
- / = concise landing page
- /manuals = manual home
- /manuals/section/[section] = section page
- /manuals/[slug] = manual detail page
- /flows/[flowKey] = operation flow page
- /search = search page
- /updates = recent updates page
- /admin = admin summary page
- /admin/manuals/[slug] = admin manual detail page

UX requirements

UI は次であること:
- clean
- responsive
- content-first
- mobile でも強く readable
- kitchens、shops、clinics、offices、back rooms の tablet 利用でも読める
- calm and legible during real operations

manual pages は実運用向けに最適化する:
- large readable step numbering
- clearly separated cautions
- clearly separated tools / materials
- minimal decorative clutter
- fast access to next / previous related procedure
- print-friendly layout
- good heading hierarchy

search は現場 staff が実用的に使える速さとわかりやすさを持つこと。

Copy は bilingual-ready でよいが、prototype は English only でも acceptable。strings は centralized すること。
日本語 labels を無理なく支えられるなら対応してよい。

Seed / demo content

少なくとも 5 つの manual documents を 2 つ以上の sections に跨って seed する。

例:
- Opening Shift Checklist
- Closing Shift Checklist
- Espresso Recipe Card
- Surface Sanitization Procedure
- POS Refund Operation
- Emergency Contact Runbook

さらに次も seed する:
- at least 1 operation flow
- at least 1 recent update event
- mixed visibility examples such as staff and manager
- at least 1 troubleshooting-style document

Developer experience

次を提供する:
- clear README
- local setup instructions
- D1 migration instructions
- content authoring instructions
- content sync instructions
- Wrangler configuration
- sample .dev.vars or environment variable documentation
- scripts for dev, test, build, sync, and deploy

Environment variables

少なくとも次を定義して documented にする:
- BASE_URL
- DEFAULT_TIMEZONE
- ACCESS_MODE
- STAFF_SHARED_SECRET
- CONTENT_SYNC_ON_START
- SEARCH_INDEX_MODE

将来の identity integration 用 placeholder として必要なら次も含める:
- ACCESS_AUDIENCE
- ACCESS_TEAM_DOMAIN
- GOOGLE_CLIENT_ID
- GOOGLE_CLIENT_SECRET

ただし prototype は external providers なしで runnable に保つこと。

Implementation guidance

visual flourish より、structure、access control、revision awareness、step rendering の correctness を優先する。
content model は non-engineer maintainers にも理解可能であること。
search と access filtering は server-authoritative にすること。
domain logic は route handlers に埋め込まず reusable modules に置くこと。
main flow の核である content sync、search、access logic を static JSON でごまかしてはならない。

Tests

少なくとも次の tests を追加する:
- frontmatter validation
- step structure validation
- content sync behavior
- revision creation / update logic
- access filtering
- search filtering
- operation flow ordering
- protected content exclusion from unauthorized results
- recent updates feed logic

Acceptance criteria

次のすべてが真になったとき prototype は complete とみなす:
1. Staff can browse a manual home
2. Staff can open structured manual pages
3. Manual pages render ordered steps, cautions, and tools / materials correctly
4. Search works across accessible manuals
5. Protected manuals are hidden from unauthorized users
6. Metadata and revision records are stored in D1
7. Recent updates feed works
8. Operation flow navigation works with previous / next behavior
9. Admin can inspect metadata and revision history
10. Content source is Markdown or MDX driven
11. Content sync is functional and documented
12. The codebase is deployable to Cloudflare with documented steps
13. Tests run successfully

Output expectations

Produce the full codebase, not just snippets.

Also include:
- D1 schema and migrations
- seed / demo manual content
- content sync logic
- README
- no placeholder skeletons for core flows
- no fake access / search logic in the main flow

Tone and naming

コード内部では実務的な English naming を使ってよい。
README と landing page では次の product meaning を示す:
「社内マニュアル魔法 / Internal Manual Spell」

landing page では少なくとも次を伝える:
- business procedures、recipes、operations handled in one structured manual foundation
- order、cautions、tools、materials、current-version awareness treated as one operational reference flow
- can later branch into staff portals、onboarding manuals、restricted departmental manuals、runbooks

Landing page content guideline

次の ideas に沿った concise landing section structure を作る:
- What spell it is
- What it can do
- Why it is useful
- Spell structure
- Familiars
- Grimoires
- Reproduction conditions
- Verification status

landing page を decorative に終わらせてはならない。actual working manual portal へ必ずリンクすること。

Final instruction

future internal manual portals、operational recipe systems、structured procedure repositories の reusable parent spell として実装せよ。
誇張より、extensibility、clarity、operational realism、maintainability、auditability を優先する。
working Cloudflare-native prototype を出荷せよ。

Execution constraints:
- planning、scaffolding、summary で止まらないこと
- content sync、search、access filtering、revision logic を fake static JSON に置き換えないこと
- access filtering は server-authoritative に保つこと
- D1 migrations を飛ばさないこと
- seed / manual content を飛ばさないこと
- tests を飛ばさないこと
- すでに指定された requirements を確認質問しないこと
- tradeoff が出たら、acceptance criteria を満たす最も単純な path を選ぶこと
- preamble と status chatter は最小限にすること
- 最後に architecture、routes、environment variables、content model、local run / deploy steps を短く要約すること

Implementation priority order:
1. content model and D1 schema
2. content parsing and sync pipeline
3. access filtering and search logic
4. manual page rendering
5. operation flow navigation
6. seeded demo manuals
7. admin inspection views
8. tests
9. README and deploy instructions