diff --git a/.cursor/rules/development_guide.mdc b/.cursor/rules/development_guide.mdc index 5b319de6..cc43b000 100644 --- a/.cursor/rules/development_guide.mdc +++ b/.cursor/rules/development_guide.mdc @@ -8,28 +8,3 @@ alwaysApply: true ✅ remove whitespace at the end of lines ✅ use npm run lint-fix to check for warnings ✅ do not use npm run dev let me handle running and supplying feedback -✅ do not add or commit for the user; let him control that process - -always preview changes and commit message to use and allow me to copy and paste -✅ Preferred Commit Message Format - - Short summary in the first line (concise and high-level). - Avoid long commit bodies unless truly necessary. - -✅ Valued Content in Commit Messages - - Specific fixes or features. - Symptoms or problems that were fixed. - Notes about tests passing or TS/linting errors being resolved (briefly). - -❌ Avoid in Commit Messages - - Vague terms: “improved”, “enhanced”, “better” — especially from AI. - Minor changes: small doc tweaks, one-liners, cleanup, or lint fixes. - Redundant blurbs: repeated across files or too generic. - Multiple overlapping purposes in a single commit — prefer narrow, focused commits. - Long explanations of what can be deduced from good in-line code comments. - - Guiding Principle - - Let code and inline documentation speak for themselves. Use commits to highlight what isn't obvious from reading the code. diff --git a/.cursor/rules/documentation.mdc b/.cursor/rules/documentation.mdc new file mode 100644 index 00000000..61f3a9e1 --- /dev/null +++ b/.cursor/rules/documentation.mdc @@ -0,0 +1,13 @@ +--- +alwaysApply: true +--- +# Directive for Documentation Generation + +1. Produce a **small, focused set of documents** rather than an overwhelming volume. +2. Ensure the content is **maintainable and worth preserving**, so that humans +are motivated to keep it up to date. +3. Prioritize **educational value**: the documents must clearly explain the +workings of the system. +4. Avoid **shallow, generic, or filler explanations** often found in +AI-generated documentation. +5. Aim for **clarity, depth, and usefulness**, so readers gain genuine understanding. diff --git a/.cursor/rules/timesafari.mdc b/.cursor/rules/timesafari.mdc index 06a39da2..3f6b77d5 100644 --- a/.cursor/rules/timesafari.mdc +++ b/.cursor/rules/timesafari.mdc @@ -1,70 +1,96 @@ --- -description: -globs: -alwaysApply: true ---- ---- -description: -globs: +description: +globs: alwaysApply: true --- # Time Safari Context ## Project Overview -Time Safari is an application designed to foster community building through gifts, gratitude, and collaborative projects. The app should make it extremely easy and intuitive for users of any age and capability to recognize contributions, build trust networks, and organize collective action. It is built on services that preserve privacy and data sovereignty. +Time Safari is an application designed to foster community building through gifts, +gratitude, and collaborative projects. The app should make it extremely easy and +intuitive for users of any age and capability to recognize contributions, build +trust networks, and organize collective action. It is built on services that +preserve privacy and data sovereignty. The ultimate goals of Time Safari are two-fold: -1. **Connect** Make it easy, rewarding, and non-threatening for people to connect with others who have similar interests, and to initiate activities together. This helps people accomplish and learn from other individuals in less-structured environments; moreover, it helps them discover who they want to continue to support and with whom they want to maintain relationships. +1. **Connect** Make it easy, rewarding, and non-threatening for people to +connect with others who have similar interests, and to initiate activities +together. This helps people accomplish and learn from other individuals in +less-structured environments; moreover, it helps them discover who they want +to continue to support and with whom they want to maintain relationships. -2. **Reveal** Widely advertise the great support and rewards that are being given and accepted freely, especially non-monetary ones. Using visuals and text, display the kind of impact that gifts are making in the lives of others. Also show useful and engaging reports of project statistics and personal accomplishments. +2. **Reveal** Widely advertise the great support and rewards that are being +given and accepted freely, especially non-monetary ones. Using visuals and text, +display the kind of impact that gifts are making in the lives of others. Also +show useful and engaging reports of project statistics and personal accomplishments. ## Core Approaches -Time Safari should help everyday users build meaningful connections and organize collective efforts by: +Time Safari should help everyday users build meaningful connections and organize +collective efforts by: -1. **Recognizing Contributions**: Creating permanent, verifiable records of gifts and contributions people give to each other and their communities. +1. **Recognizing Contributions**: Creating permanent, verifiable records of gifts +and contributions people give to each other and their communities. -2. **Facilitating Collaboration**: Making it ridiculously easy for people to ask for or propose help on projects and interests that matter to them. +2. **Facilitating Collaboration**: Making it ridiculously easy for people to ask +for or propose help on projects and interests that matter to them. -3. **Building Trust Networks**: Enabling users to maintain their network and activity visibility. Developing reputation through verified contributions and references, which can be selectively shown to others outside the network. +3. **Building Trust Networks**: Enabling users to maintain their network and activity +visibility. Developing reputation through verified contributions and references, +which can be selectively shown to others outside the network. -4. **Preserving Privacy**: Ensuring personal identifiers are only shared with explicitly authorized contacts, allowing private individuals including children to participate safely. +4. **Preserving Privacy**: Ensuring personal identifiers are only shared with +explicitly authorized contacts, allowing private individuals including children +to participate safely. -5. **Engaging Content**: Displaying people's records in compelling stories, and highlighting those projects that are lifting people's lives long-term, both in physical support and in emotional-spiritual-creative thriving. +5. **Engaging Content**: Displaying people's records in compelling stories, and +highlighting those projects that are lifting people's lives long-term, both in +physical support and in emotional-spiritual-creative thriving. ## Technical Foundation -This application is built on a privacy-preserving claims architecture (via endorser.ch) with these key characteristics: +This application is built on a privacy-preserving claims architecture (via +endorser.ch) with these key characteristics: -- **Decentralized Identifiers (DIDs)**: User identities are based on public/private key pairs stored on their devices -- **Cryptographic Verification**: All claims and confirmations are cryptographically signed -- **User-Controlled Visibility**: Users explicitly control who can see their identifiers and data -- **Merkle-Chained Claims**: Claims are cryptographically chained for verification and integrity -- **Native and Web App**: Works on Capacitor (iOS, Android), Desktop (Electron and CEFPython), and web browsers +- **Decentralized Identifiers (DIDs)**: User identities are based on public/private +key pairs stored on their devices +- **Cryptographic Verification**: All claims and confirmations are +cryptographically signed +- **User-Controlled Visibility**: Users explicitly control who can see their +identifiers and data +- **Merkle-Chained Claims**: Claims are cryptographically chained for verification +and integrity +- **Native and Web App**: Works on Capacitor (iOS, Android), Desktop (Electron +and CEFPython), and web browsers ## User Journey The typical progression of usage follows these stages: -1. **Gratitude & Recognition**: Users begin by expressing and recording gratitude for gifts received, building a foundation of acknowledgment. +1. **Gratitude & Recognition**: Users begin by expressing and recording gratitude +for gifts received, building a foundation of acknowledgment. -2. **Project Proposals**: Users propose projects and ideas, reaching out to connect with others who share similar interests. +2. **Project Proposals**: Users propose projects and ideas, reaching out to connect +with others who share similar interests. -3. **Action Triggers**: Offers of help serve as triggers and motivations to execute proposed projects, moving from ideas to action. +3. **Action Triggers**: Offers of help serve as triggers and motivations to execute +proposed projects, moving from ideas to action. ## Context for LLM Development When developing new functionality for Time Safari, consider these design principles: -1. **Accessibility First**: Features should be usable by non-technical users with minimal learning curve. +1. **Accessibility First**: Features should be usable by non-technical users with +minimal learning curve. 2. **Privacy by Design**: All features must respect user privacy and data sovereignty. -3. **Progressive Enhancement**: Core functionality should work across all devices, with richer experiences where supported. +3. **Progressive Enhancement**: Core functionality should work across all devices, +with richer experiences where supported. 4. **Voluntary Collaboration**: The system should enable but never coerce participation. @@ -72,31 +98,40 @@ When developing new functionality for Time Safari, consider these design princip 6. **Network Effects**: Consider how features scale as more users join the platform. -7. **Low Resource Requirements**: The system should be lightweight enough to run on inexpensive devices users already own. +7. **Low Resource Requirements**: The system should be lightweight enough to run +on inexpensive devices users already own. ## Use Cases to Support LLM development should focus on enhancing these key use cases: -1. **Community Building**: Tools that help people find others with shared interests and values. +1. **Community Building**: Tools that help people find others with shared +interests and values. -2. **Project Coordination**: Features that make it easy to propose collaborative projects and to submit suggestions and offers to existing ones. +2. **Project Coordination**: Features that make it easy to propose collaborative +projects and to submit suggestions and offers to existing ones. -3. **Reputation Building**: Methods for users to showcase their contributions and reliability, in contexts where they explicitly reveal that information. +3. **Reputation Building**: Methods for users to showcase their contributions +and reliability, in contexts where they explicitly reveal that information. -4. **Governance Experimentation**: Features that facilitate decision-making and collective governance. +4. **Governance Experimentation**: Features that facilitate decision-making and +collective governance. ## Constraints When developing new features, be mindful of these constraints: -1. **Privacy Preservation**: User identifiers must remain private except when explicitly shared. +1. **Privacy Preservation**: User identifiers must remain private except when +explicitly shared. -2. **Platform Limitations**: Features must work within the constraints of the target app platforms, while aiming to leverage the best platform technology available. +2. **Platform Limitations**: Features must work within the constraints of the target +app platforms, while aiming to leverage the best platform technology available. -3. **Endorser API Limitations**: Backend features are constrained by the endorser.ch API capabilities. +3. **Endorser API Limitations**: Backend features are constrained by the endorser.ch +API capabilities. -4. **Performance on Low-End Devices**: The application should remain performant on older/simpler devices. +4. **Performance on Low-End Devices**: The application should remain performant +on older/simpler devices. 5. **Offline-First When Possible**: Key functionality should work offline when feasible. @@ -122,6 +157,7 @@ When developing new features, be mindful of these constraints: ## Core Development Principles ### DRY development + - **Code Reuse** - Extract common functionality into utility functions - Create reusable components for UI patterns @@ -177,8 +213,9 @@ When developing new features, be mindful of these constraints: - Use shared test configurations - Create reusable test helpers - Implement consistent test patterns - + ### SOLID Principles + - **Single Responsibility**: Each class/component should have only one reason to change - Components should focus on one specific feature (e.g., QR scanning, DID management) - Services should handle one type of functionality (e.g., platform services, crypto services) @@ -205,6 +242,7 @@ When developing new features, be mindful of these constraints: - Implement factory patterns for component creation ### Law of Demeter + - Components should only communicate with immediate dependencies - Avoid chaining method calls (e.g., `this.service.getUser().getProfile().getName()`) - Use mediator patterns for complex component interactions @@ -212,6 +250,7 @@ When developing new features, be mindful of these constraints: - Keep component communication through defined events and props ### Composition over Inheritance + - Prefer building components through composition - Use mixins for shared functionality - Implement feature toggles through props @@ -219,6 +258,7 @@ When developing new features, be mindful of these constraints: - Use service composition for complex features ### Interface Segregation + - Define clear interfaces for services - Keep component APIs minimal and focused - Split large interfaces into smaller, specific ones @@ -226,6 +266,7 @@ When developing new features, be mindful of these constraints: - Implement role-based interfaces for different use cases ### Fail Fast + - Validate inputs early in the process - Use TypeScript strict mode - Implement comprehensive error handling @@ -233,6 +274,7 @@ When developing new features, be mindful of these constraints: - Use assertions for development-time validation ### Principle of Least Astonishment + - Follow Vue.js conventions consistently - Use familiar naming patterns - Implement predictable component behaviors @@ -240,6 +282,7 @@ When developing new features, be mindful of these constraints: - Keep UI interactions intuitive ### Information Hiding + - Encapsulate implementation details - Use private class members - Implement proper access modifiers @@ -247,6 +290,7 @@ When developing new features, be mindful of these constraints: - Use TypeScript's access modifiers effectively ### Single Source of Truth + - Use Pinia for state management - Maintain one source for user data - Centralize configuration management @@ -254,6 +298,7 @@ When developing new features, be mindful of these constraints: - Implement proper state synchronization ### Principle of Least Privilege + - Implement proper access control - Use minimal required permissions - Follow privacy-by-design principles @@ -261,6 +306,7 @@ When developing new features, be mindful of these constraints: - Implement proper authentication/authorization ### Continuous Integration/Continuous Deployment (CI/CD) + - Automated testing on every commit - Consistent build process across platforms - Automated deployment pipelines @@ -268,9 +314,9 @@ When developing new features, be mindful of these constraints: - Environment-specific configurations This expanded documentation provides: + 1. Clear principles for development 2. Practical implementation guidelines 3. Real-world examples 4. TypeScript integration 5. Best practices for Time Safari - diff --git a/.cursor/rules/version_control.mdc b/.cursor/rules/version_control.mdc new file mode 100644 index 00000000..c486997d --- /dev/null +++ b/.cursor/rules/version_control.mdc @@ -0,0 +1,28 @@ +--- +alwaysApply: true +--- + do not add or commit for the user; let him control that process + +always preview changes and commit message to use and allow me to copy and paste +✅ Preferred Commit Message Format + + Short summary in the first line (concise and high-level). + Avoid long commit bodies unless truly necessary. + +✅ Valued Content in Commit Messages + + Specific fixes or features. + Symptoms or problems that were fixed. + Notes about tests passing or TS/linting errors being resolved (briefly). + +❌ Avoid in Commit Messages + + Vague terms: “improved”, “enhanced”, “better” — especially from AI. + Minor changes: small doc tweaks, one-liners, cleanup, or lint fixes. + Redundant blurbs: repeated across files or too generic. + Multiple overlapping purposes in a single commit — prefer narrow, focused commits. + Long explanations of what can be deduced from good in-line code comments. + + Guiding Principle + + Let code and inline documentation speak for themselves. Use commits to highlight what isn't obvious from reading the code.