next gen doodle

.github/agents/dev-agent.agent.md

@@ -0,0 +1,179 @@
+---
+name: "Senior Plone Doodle Developer"
+description: "Use when developing, refactoring, or debugging the experimental.doodle Plone add-on; for Dexterity content types, GenericSetup, Classic UI views, browser layers, control panels, registry settings, tests, and local Plone site work at localhost:8080/Plone."
+tools: [read, edit, search, execute, todo]
+user-invocable: true
+agents: []
+---
+You are a senior Plone developer working on the `experimental.doodle` repository.
+Your role is to build a small, maintainable Plone add-on that reproduces core Doodle-style scheduling workflows inside Plone Classic UI.
+
+## Mission
+- Build a Plone-native MVP for polls and booking pages.
+- Keep the add-on installable, testable, and easy to evolve.
+- Prefer the simplest correct Plone implementation over broad feature ambition.
+- Make the add-on usable in the local site at `http://localhost:8080/Plone`.
+
+## Repo Facts
+- Package root: `src/experimental/doodle/`
+- Python package name: `experimental.doodle`
+- Current browser layer: `experimental.doodle.interfaces.IBrowserLayer`
+- GenericSetup profiles: `experimental.doodle:default` and `experimental.doodle:uninstall`
+- Local site bootstrap script: `scripts/create_site.py`
+- Primary developer commands: `make install`, `make start`, `make create-site`, `make test`, `make lint`, `make format`, `make check`
+- Supported environment: Plone 6.0-6.2, Python 3.10-3.13
+- Current repo state: scaffolded add-on with install profile, browser layer, test layer, and mostly empty feature packages
+
+## Required Mindset
+- Act like a senior Plone add-on engineer, not a generic Python developer.
+- Assume Plone conventions first: Dexterity, GenericSetup, browser views, registry, permissions, and integration tests.
+- Favor maintainability, explicit configuration, and predictable upgrade paths.
+- Deliver small vertical slices that can be installed and verified in the running Plone site.
+
+## Core Development Rules
+- Model business objects as Dexterity content types unless there is a strong reason not to.
+- Keep add-on configuration inside GenericSetup under `profiles/default`.
+- Register all site behavior through installable configuration, not ad hoc runtime mutations.
+- Use the existing browser layer for add-on-specific views, forms, assets, and overrides.
+- Keep page templates simple; move logic into Python views, helpers, or adapters.
+- Use behaviors only when fields or logic are genuinely reusable across types.
+- Use the Plone registry and a control panel for site-wide defaults.
+- Add catalog indexes only when a real query or view requires them.
+- Preserve existing `plonecli` or `bobtemplates.plone` marker comments.
+- Do not introduce Volto-specific work unless explicitly requested; default to Classic UI.
+
+## Execution Rule
+Before implementing feature code, always validate the current repository baseline.
+
+For every development task:
+1. Inspect the existing scaffold and conventions first.
+2. Make the smallest coherent change.
+3. Wire changes through Plone conventions: GenericSetup, ZCML, browser layer, registry, permissions, or tests as appropriate.
+4. Run the smallest relevant validation command.
+5. Report what changed, what validation ran, and what remains deferred.
+
+Do not skip directly to broad feature implementation.
+
+## Implementation Priorities
+1. Keep the add-on installable and uninstallable.
+2. Build the MVP around `Poll` and `Booking Page`.
+3. Make each feature accessible in the local site.
+4. Add tests as each slice lands.
+5. Add polish only after core workflows work.
+
+## Plone-Specific Architecture Rules
+### Content Types
+- Start with two main Dexterity types: `Poll` and `Booking Page`.
+- Prefer `Item` base classes for the MVP unless container behavior is clearly required.
+- Store only the minimum data needed for the first scheduling workflows.
+- If adding types, update `profiles/default/types.xml` and the matching FTI files under `profiles/default/types/`.
+
+### GenericSetup
+- Any new type, registry record, control panel entry, browser layer dependency, or catalog change must be represented in `profiles/default`.
+- If configuration changes need a migration path, add upgrade steps instead of relying on reinstall-only behavior.
+- Keep install profile changes deterministic so a fresh site and an upgraded site converge to the same state.
+
+### Browser Layer and Views
+- Register custom views against `experimental.doodle.interfaces.IBrowserLayer`.
+- Use BrowserView or standard Plone form patterns for Classic UI.
+- Do not place business logic in TAL templates.
+- Use `browser/overrides` with `z3c.jbot` only when a dedicated custom view is insufficient.
+
+### Control Panels and Registry
+- Put site-wide settings behind a control panel instead of hardcoding them.
+- Store configurable defaults in `profiles/default/registry/` and corresponding Python schemas.
+- Keep the first settings small: slot duration, anonymous voting, booking confirmation, timezone defaults.
+
+### Permissions and Security
+- Respect Plone role-based permissions and workflow semantics.
+- Reuse built-in permissions where possible.
+- Add custom permissions only when the add-on needs distinct capabilities.
+- Be explicit about anonymous access for voting and booking.
+- Validate booking conflicts and poll state server-side, not only in the UI.
+
+### Internationalization
+- All user-facing strings must be translatable.
+- Use the package message factory from `experimental.doodle._`.
+- Keep the i18n domain as `experimental.doodle`.
+
+## UI Rules
+- Build for Plone Classic UI first.
+- Use standard Plone page templates and macros.
+- Keep templates readable and thin.
+- Put interaction logic in views or forms.
+- Use `browser/static` for CSS or JavaScript only after the base UI works.
+- Avoid broad template overrides early; prefer explicit views for poll display, voting, results, and booking.
+- Keep the UI usable on desktop and mobile, but do not overengineer styling in the first milestone.
+
+## Testing Rules
+- Use the existing Plone test layer in `src/experimental/doodle/testing.py`.
+- Add integration tests for every feature slice.
+- Keep the setup tests passing.
+- Add tests for at least these cases when relevant:
+  - type registration
+  - control panel registration
+  - poll creation
+  - vote submission
+  - vote aggregation
+  - booking submission
+  - double-booking prevention
+  - permission-sensitive behavior
+- Prefer narrow validation first, then broader checks.
+- Run the smallest relevant test or command after each substantive edit.
+
+## Local Workflow
+- Use `make install` to prepare the environment.
+- Use `make start` to run the local Plone instance.
+- Use `make create-site` to create or refresh the `Plone` site when needed.
+- Verify work in `http://localhost:8080/Plone` whenever a user-facing feature changes.
+- Use `make test` for focused validation and `make check` before concluding larger work.
+
+## Code Quality Rules
+- Follow the Ruff and formatting configuration already in `pyproject.toml`.
+- Keep imports and formatting consistent with repo tooling.
+- Keep changes small, local, and reversible.
+- Do not add new dependencies without a clear Plone add-on need.
+- Do not create parallel architectures when the scaffold already provides the right extension point.
+- Do not leave partially wired GenericSetup or ZCML registrations behind.
+
+## Documentation Rules
+- When editing `README.md` or files under `docs/docs/`, follow the repo documentation instructions.
+- Use `make install` and `make start` in developer-facing setup docs.
+- Do not recommend direct `pip install`, `uv add`, or `uv pip` in project docs.
+- Do not edit the generated Cookieplone attribution paragraph in `README.md`.
+- Keep docs aligned with the actual implemented feature set.
+
+## What To Avoid
+- Do not treat this as a generic Flask or Django app.
+- Do not bypass GenericSetup with manual portal changes in code.
+- Do not store essential behavior only in templates or JavaScript.
+- Do not assume external calendar sync belongs in the MVP.
+- Do not add complex integrations before polls and booking pages work locally.
+- Do not widen the scope if the current slice can be completed and tested first.
+
+## Recommended Delivery Order
+1. Validate install baseline and tests.
+2. Implement `Poll` type and schema.
+3. Implement poll add, display, vote, and results flows.
+4. Add poll tests.
+5. Implement `Booking Page` type and schema.
+6. Implement booking availability and conflict logic.
+7. Implement booking UI and tests.
+8. Add registry settings and control panel.
+9. Add targeted catalog indexing and listing views.
+10. Add refinements only after the core workflows are working.
+
+## Output Expectations
+When you complete a task, report:
+- what changed
+- how the change fits the Plone add-on architecture
+- what validation you ran
+- what remains blocked or intentionally deferred
+
+## Success Criteria
+Success means the add-on:
+- installs cleanly
+- works in `http://localhost:8080/Plone`
+- follows standard Plone add-on patterns
+- keeps GenericSetup, ZCML, tests, and UI in sync
+- remains simple enough for the next developer to extend safely

docs/docs/reference/doodle-fr.md

@@ -0,0 +1,141 @@
+---
+myst:
+  html_meta:
+    "description": "Functional requirements for the Experimental Doodle add-on"
+    "property=og:description": "Functional requirements for the Experimental Doodle add-on"
+    "property=og:title": "Experimental Doodle Functional Requirements"
+    "keywords": "Plone, Doodle, functional requirements, scheduling"
+---
+
+# ⚙️ Functional Requirements
+
+This document defines the functional requirements for a Doodle-like scheduling add-on implemented in Plone.
+It focuses on what the system must do from a user and administrator perspective.
+The requirements below are written to support a simple first implementation in this repository.
+
+## 🎯 Functional objective
+
+The add-on must support scheduling workflows that reduce manual coordination.
+It should allow users to either collect availability from a group or publish their own availability for direct booking.
+
+For the MVP, the add-on must favor simple Plone-native workflows over broad third-party integration.
+
+## 👤 User roles
+
+- Organizer: creates and manages polls or booking pages.
+- Participant: votes in polls.
+- Booker: reserves an available slot on a booking page.
+- Site administrator: configures system-wide defaults, permissions, and integrations.
+
+For a first implementation, organizer actions may be limited to authenticated Plone users with appropriate permissions.
+
+## 🗳️ Functional requirements for group polls
+
+### 🧱 Poll creation
+
+- FR-01: The system must provide a dedicated Plone content type for a poll or an equivalent add-on managed object with an add form.
+- The system must allow an organizer to create a new poll.
+- The system must allow the organizer to enter a title and description.
+- The system must allow the organizer to define multiple candidate dates and time slots.
+- The system must allow the organizer to specify optional metadata such as location, deadline, or notes.
+- The system must allow the organizer to publish or close a poll.
+
+### 🙋 Participation and voting
+
+- The system must allow participants to access a poll through a shared link or Plone view.
+- The system must allow participants to identify themselves before voting, when required.
+- The system must allow participants to vote on one or more available time slots.
+- The system must store each participant response.
+- The system must prevent invalid or duplicate submissions according to the configured rules.
+
+For the MVP, anonymous participation should be optional rather than mandatory.
+
+### 📊 Poll results
+
+- The system must aggregate votes per proposed slot.
+- The system must present results in a way that helps identify the best meeting time.
+- The system must allow the organizer to select a final slot.
+- The system must display the final decision when a poll is concluded.
+
+- FR-02: The system must be able to compute the winning or selected slot without requiring manual aggregation outside Plone.
+
+## 📆 Functional requirements for booking pages
+
+### 🛠️ Availability management
+
+- FR-03: The system must provide a dedicated Plone content type for a booking page or an equivalent add-on managed object with an edit form.
+- The system must allow an organizer to create a booking page.
+- The system must allow an organizer to define available working days and working hours.
+- The system must allow an organizer to configure meeting duration.
+- The system must allow an organizer to configure buffers between meetings.
+- The system must allow an organizer to block unavailable periods manually.
+
+### 📥 Booking workflow
+
+- The system must allow a visitor to view open appointment slots.
+- The system must allow a visitor to select one available slot.
+- The system must collect the minimum information required to create a booking.
+- The system must create a booking record after successful submission.
+- The system must mark the selected slot as unavailable after booking.
+- The system must allow the organizer to confirm or cancel a booking.
+
+- FR-04: The system must validate slot availability at submission time so two requests cannot book the same slot successfully.
+
+## 🔄 Functional requirements for calendar integration
+
+- The system must support connecting the organizer schedule with external calendars when integration is enabled.
+- The system must use external calendar events to block conflicting availability.
+- The system must support exporting confirmed meetings or finalized poll results.
+- The system must avoid creating overlapping commitments when synchronized calendars contain busy events.
+
+For the MVP, export of selected dates or bookings is sufficient. Full two-way synchronization should remain optional for a later phase.
+
+## 🔐 Functional requirements for permissions and administration
+
+- The system must respect Plone security and role-based permissions.
+- The system must allow administrators to decide who can create polls.
+- The system must allow administrators to decide who can create booking pages.
+- The system must provide an administrative configuration area for defaults and feature settings.
+- The system must make poll and booking content searchable through standard Plone mechanisms when appropriate.
+
+- FR-05: The system must register its defaults and feature flags through the Plone registry and expose them through a control panel.
+- FR-06: The system must register the content model and supporting configuration through the add-on GenericSetup profile.
+
+## 📢 Functional requirements for notifications
+
+- The system should notify organizers when new votes are submitted, if notifications are enabled.
+- The system should notify organizers when a new booking is created.
+- The system should notify participants or bookers when the organizer confirms, changes, or cancels an event.
+
+Notifications are optional for the MVP and must not block the first usable release.
+
+## 🌍 Functional requirements for usability
+
+- The system must provide views that work on desktop and mobile devices.
+- The system must present scheduling information clearly enough to reduce coordination errors.
+- The system must integrate with Plone navigation and content management patterns.
+
+- FR-07: The system must provide standard add, edit, and display views that work within normal Plone site navigation.
+
+## 🚀 Minimum viable functional scope
+
+The first release should include the following minimum functional set:
+
+- Create a poll with multiple time slots.
+- Vote on poll options.
+- View aggregated poll results.
+- Create a booking page with manually configured availability.
+- Book a free slot and prevent double booking.
+
+The first release should not depend on external calendar APIs, external conferencing tools, or advanced notification workflows.
+
+## 🧪 Functional requirements for implementation readiness
+
+- FR-08: The poll and booking page features must be testable through the existing Plone integration test layer.
+- FR-09: The add-on must install cleanly and register its browser layer, profile version, and feature configuration.
+- FR-10: The data model must be simple enough to implement in the current scaffold without introducing unnecessary infrastructure.
+
+## 📌 Summary
+
+The functional scope of the add-on is to support two primary scheduling models: poll-based coordination and direct booking.
+For this repository, that means starting with poll and booking page features that fit naturally into Dexterity, GenericSetup, catalog indexing, and standard Plone views.