Treat procedures, recipes, checklists, and runbooks as one internal manual structure

You are Codex. Build a production-shaped prototype called “社内マニュアル魔法 / Internal Manual Spell” on Cloudflare.

Your job is not to write a concept page. Your job is to implement a working internal manual system prototype that treats business procedures, recipes, operating instructions, cautions, prerequisites, and revision history as one unified manual structure.

Operate in a high-autonomy, non-interactive style.
Do not ask clarifying questions.
Make reasonable assumptions and implement the full prototype end-to-end with clear code, comments, type safety, validation, and deployability.

Project goal

Build a reusable internal manual system for operational procedures, recipes, SOPs, checklists, workstation instructions, service flows, cleaning routines, opening/closing tasks, and similar internal operational documentation.

The system must support:
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

Treat procedures, recipes, and operations as one parent manual structure.

The system must make it easy to understand:
- what to do
- in what order
- with what tools or materials
- under what cautions
- who should read it
- what the current version is
- what changed recently

This is not just a general knowledge base.
It is a structured internal manual foundation where operational sequence, required items, warnings, and version control are first-class.

Use the following framing in code comments and naming where helpful:
- Procedure Familiar = structures steps, prerequisites, tools, materials, cautions, and checks
- Access Familiar = controls who can read what
- Revision Familiar = preserves version flow and keeps stale instructions from lingering unnoticed

The architecture must also be ready to connect later to:
- training portals
- onboarding flows
- sign-off / read acknowledgement flows
- restricted departmental manuals
- policy distribution
- incident response runbooks

Non-goals for this prototype

Do not build a full CMS.
Do not build a collaborative rich-text editor.
Do not build full HR training compliance tracking.
Do not build e-signature workflows.
Do not build video hosting as a required dependency.
Do not overcomplicate permissions beyond a practical staff/admin model with role-aware filtering.

Fixed stack

Use this exact stack unless absolutely impossible:
- Frontend: Astro + TypeScript
- Interactive UI where needed: minimal React islands
- Content source: Markdown or MDX files in the repository
- Backend/API: Cloudflare Pages Functions or Cloudflare Workers, choose the simplest Cloudflare-native route
- Database: Cloudflare D1
- Auth: Cloudflare Access compatible staff gate
- Search: lightweight server-side search index over metadata and step text, stored in D1 or regenerated during sync
- Validation: Zod
- Testing: Vitest at minimum
- Styling: clean CSS, content-first, no UI library required

Architecture

Use a repository layout such as:
- apps/web = Astro frontend and admin UI
- content/manuals = Markdown or MDX source files
- packages/shared = shared types, validation schemas, content parsing, search, access logic, revision logic

If you choose a simpler structure, still maintain clear separation between:
- manual source content
- content sync and parsing
- metadata/revision logic
- access control
- search
- frontend rendering
- admin inspection views

Functional requirements

1. Structured manual types

Support at least these manual content types:
- procedure
- recipe
- checklist
- runbook
- troubleshooting

Each manual document must support metadata such as:
- 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

Each manual must support clearly structured steps.

A step should support:
- step number
- title optional
- instruction text
- duration minutes optional
- caution text optional
- quality check or success condition optional
- note optional

This structure must render cleanly in the UI.
Do not reduce procedures to an unstructured block of text.

3. Recipe and operation structure

Recipe-style manuals should be able to show:
- ingredients or materials
- quantity text
- yield or batch note optional
- preparation notes
- ordered steps

Operation-style manuals should be able to show:
- prerequisites
- tools
- opening/closing or execution sequence
- checkpoints
- failure or troubleshooting notes

4. Role-based access control

Implement access control suitable for internal manuals.

At minimum support:
- staff
- manager
- admin

You may also support public or authenticated if useful, but the default assumption is internal staff documentation.

Access control must apply to:
- page rendering
- API responses
- search results
- navigation lists
- update feeds

Do not leak protected document metadata to unauthorized users.

5. Revision and update model

Implement a revision-aware structure.

Each manual must support:
- one canonical current version
- revision metadata
- updated_at timestamp
- changelog summary optional
- revision history in D1

For this prototype:
- store manual source in Markdown or MDX
- store metadata and revision records in D1
- expose last updated and version info in UI
- show a recent updates feed

You do not need to build an in-browser editor, but the content maintenance flow must be clear and real.

6. Search

Implement working search across accessible manual content.

Search must support:
- title
- summary
- tags
- section
- manual type
- step text
- caution text where practical

Search results must:
- respect access control
- link to manual pages
- show manual type and updated date
- support filtering by type or section if practical

7. Operation flow / ordered navigation

Implement an operation flow or ordered manual sequence capability.

At minimum:
- 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

Create at least one example operation flow such as:
- Opening Shift Flow
or
- Daily Kitchen Prep Flow

8. Manual page experience

Each manual page must clearly show:
- 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

Also support:
- print-friendly layout
- compact mobile reading
- optional checklist mode with local state only

Checklist mode can be implemented with client-side local state and does not need server persistence.

9. Recent updates visibility

Implement an updates feed that shows:
- recently changed manuals
- version label
- update date
- changelog summary where available

This helps prevent outdated instructions from surviving in silence.

10. Admin/staff inspection view

Build a staff-only admin area that can:
- list manuals
- filter by type, visibility, section, status
- inspect manual metadata
- inspect step structure
- inspect revision history
- inspect recent update events
- inspect operation flow structure
- trigger content sync manually

Do not overbuild a CMS. Keep it operational and readable.

11. Content sync from repository

Implement a content sync flow that:
- reads Markdown or MDX files from the content directory
- validates frontmatter and step structure with Zod
- inserts or updates metadata in D1
- creates new revision records when source content changes
- refreshes search index data

The sync must be deterministic and documented.

12. Future readiness

Design the architecture so it can later support:
- read acknowledgement
- departmental targeting
- media attachments
- import from external source repositories
- scheduled sync jobs
- richer identity provider integration

You do not need to fully implement those features now, but the structure must not block them.

Data model

Design and implement D1 schema for at least these tables:

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 optional if useful, but only add it if it clearly improves implementation practicality.

Do not bloat the first prototype unnecessarily.

Content source model

Store manual source as Markdown or MDX files with frontmatter.

Frontmatter should support fields such as:
- title
- slug
- summary
- manualType
- section
- chapter
- visibility
- status
- version
- updatedAt
- tags
- audience
- estimatedMinutes
- prerequisites
- tools
- materials
- yieldText
- operationFlow
- flowOrder
- changelogSummary

The source file should also support structured step data.
Use one practical approach such as:
- YAML frontmatter with a steps array of objects
or
- MDX components for steps
Choose the simplest path that still yields robust structured rendering and sync behavior.

Validate the content model with Zod.

Security

Implement safe practices:
- validate all content metadata with Zod
- validate all API input
- protect staff/admin routes with a clear auth middleware stub
- do not expose protected manuals through search, navigation, or update feeds
- sanitize search input
- return useful but not oversharing error messages

API design

Implement JSON endpoints roughly like:

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

You may adjust naming, but preserve these capabilities.

Frontend pages

Build at least these pages:
- / = concise landing page for the prototype
- /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

The UI must be:
- clean
- responsive
- content-first
- strongly readable on mobile
- usable on tablets in kitchens, shops, clinics, offices, and back rooms
- calm and legible during real operations

Manual pages should be optimized for actual work:
- 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 should feel fast and practical for real staff use.

Copy can be bilingual-ready, but implementing English only is acceptable for the prototype as long as strings are centralized for later localization.
If you can support Japanese labels cleanly without slowing development, do so.

Seed/demo content

Seed the system with at least 5 manual documents across at least 2 sections.

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

Also 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

Provide:
- 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

Define and document environment variables for at least:
- BASE_URL
- DEFAULT_TIMEZONE
- ACCESS_MODE
- STAFF_SHARED_SECRET
- CONTENT_SYNC_ON_START
- SEARCH_INDEX_MODE

If needed for future identity integration, include placeholders for:
- ACCESS_AUDIENCE
- ACCESS_TEAM_DOMAIN
- GOOGLE_CLIENT_ID
- GOOGLE_CLIENT_SECRET

But keep the prototype runnable without external providers.

Implementation guidance

Prioritize correctness of structure, access control, revision awareness, and step rendering over visual flourish.
Keep the content model understandable for non-engineer maintainers.
Keep search and access filtering server-authoritative.
Keep domain logic in reusable modules rather than embedding it directly inside route handlers.
Do not fake the main flow with static JSON when content sync and access logic are core requirements.

Tests

Add tests for at least:
- 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

The prototype is considered complete only if all of the following are true:
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

Internally, you may use practical English naming in code.
In the README and landing page, describe the system as:
“社内マニュアル魔法 / Internal Manual Spell”

On the landing page, reflect this product meaning:
- business procedures, recipes, and operations handled in one structured manual foundation
- order, cautions, tools, materials, and current-version awareness treated as one operational reference flow
- can later branch into staff portals, onboarding manuals, restricted departmental manuals, and runbooks

Landing page content guideline

Create a concise landing page section structure inspired by the following ideas:
- What spell it is
- What it can do
- Why it is useful
- Spell structure
- Familiars
- Grimoires
- Reproduction conditions
- Verification status

Do not make the landing page merely decorative. The actual working manual portal must exist and be linked from it.

Final instruction

Implement this as a reusable parent spell for future internal manual portals, operational recipe systems, and structured procedure repositories.
Favor extensibility, clarity, operational realism, maintainability, and auditability over hype.
Ship a working Cloudflare-native prototype.

Execution constraints:
- Do not stop at planning, scaffolding, or summarizing
- Do not replace content sync, search, access filtering, or revision logic with fake static JSON
- Keep access filtering server-authoritative
- Do not skip D1 migrations
- Do not skip seed/manual content
- Do not skip tests
- Do not ask for requirements already specified above
- If tradeoffs appear, choose the simplest path that still fully satisfies the acceptance criteria
- Minimize preambles and status chatter
- When finished, provide a short summary of architecture, routes, environment variables, content model, and 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