# AI Collaboration Guide for the Noteplace Project

This document outlines the preferred working style and conventions for AI collaboration on this project, based on initial interactions and feedback.

## 1. Core Philosophy: Incremental, Verifiable Milestones

- **Break It Down**: Do not attempt to implement large, complex features in a single step. Decompose work into the smallest possible, verifiable milestones.
- **No Mocks in Milestones**: A milestone is only considered "done" when its features are fully functional and integrated with the live backend API. Mocked implementations are only acceptable as a temporary step *within* a milestone, not as the final deliverable for one.
- **Test Before Moving On**: After a feature is implemented, it must be tested and verified before starting the next task.

## 2. The "Polish Phase"

After a functional milestone is complete, a dedicated "polish phase" is required. This is a critical step and should not be skipped. This phase includes:

- **Documentation**: Update the `README.md`, `docs/WORKLOG.md`, and any other relevant documentation.
- **Testing**: Add unit or integration tests for the new functionality. The preferred framework for the frontend is `vitest`.
- **Code Quality**: Clean up any temporary or "useless" code. Refactor to improve clarity and maintainability.
- **Production Readiness**: Remove hardcoded values (e.g., URLs, tokens) and replace them with environment variables.
- **Repository Health**: Ensure the repository is well-structured. This includes adding or updating files like `.gitignore` and CI/CD workflows.

## 3. Backend & Environment Interaction

- **Backend is Truth**: The Go backend is the source of truth. Before implementing a frontend feature, verify that the required backend endpoint exists and functions as expected.
- **Identify Backend Gaps**: If a required backend feature is missing (e.g., a web auth endpoint for a web app), the AI must:
    1.  Clearly identify and explain the gap.
    2.  Propose the correct, standard solution.
    3.  Offer to implement the necessary changes in the backend code.
- **Handle Environment Constraints**: The development environment may have limitations (e.g., shell commands like `npm` failing). The AI should not get stuck. It should diagnose the issue, and if it cannot be resolved, propose a manual workaround (like editing `package.json` directly) and clearly ask the user for help with running the required commands (e.g., `npm install`).

## 4. Project-Specific Conventions

- **CI/CD**: The project uses both **GitHub Actions** and **Gitea**. When adding a CI/CD workflow, create configuration files for both systems (`.github/workflows/` and `.gitea/workflows/`).
- **Backend Logging**: When modifying backend code, add meaningful logs using the existing `zap` logger to trace the execution flow.
- **User-AI Interaction**: The user prefers clear, step-by-step explanations, especially for complex topics (like OAuth2). The AI should be proactive in its explanations and planning.