sublation-os 1.0.0

package/.sublation-os/memory/index.md

@@ -0,0 +1,94 @@
+# Memory System Index
+
+This index helps you quickly find relevant learnings across all memory files in the Sublation-OS framework.
+
+**Last Updated:** 2025-11-04
+
+---
+
+## 📚 Table of Contents
+
+### Learning Categories
+
+1. **[Backend Lessons](backend-lessons.md)** - APIs, databases, services, server-side logic
+2. **[Frontend Lessons](frontend-lessons.md)** - UI components, state management, user interactions
+3. **[Testing Lessons](testing-lessons.md)** - Testing strategies, frameworks, mocking, QA
+4. **[Architecture Lessons](architecture-lessons.md)** - System design, patterns, project structure
+5. **[General Lessons](general-lessons.md)** - Workflow, tooling, debugging, cross-functional
+
+### Legacy Files
+
+- **[learned-lessons.md](learned-lessons.md)** - Original unified file (maintained for backward compatibility)
+
+---
+
+## 🏷️ Tag Index
+
+This section will be automatically updated as you add learnings. Use tags to find related lessons across categories.
+
+### Common Tags
+- `#performance` - Performance optimization learnings
+- `#database` - Database-related learnings
+- `#api` - API design and implementation
+- `#testing` - Testing strategies and techniques
+- `#security` - Security best practices
+- `#patterns` - Design patterns and architecture
+- `#debugging` - Debugging techniques
+- `#tooling` - Development tools and workflows
+
+---
+
+## 📝 Recent Learnings
+
+*This section shows the most recent 10 learnings across all categories*
+
+No learnings recorded yet. Use `/sublation-os:learn` to capture your first learning!
+
+---
+
+## 🔍 How to Search
+
+### By Category
+1. Click on the category link above to browse all learnings in that domain
+2. Each file is organized chronologically with the most recent learnings at the bottom
+
+### By Tag
+1. Find tags in the Tag Index section above
+2. Use Ctrl+F within category files to search for specific tags (format: `#tagname`)
+
+### By Keyword
+1. Use the `/sublation-os:recall` command to search across all memory files
+2. Or use Ctrl+F to search within specific category files
+
+---
+
+## ✍️ Adding New Learnings
+
+Use the `/sublation-os:learn` command to capture new learnings. The command will:
+1. Prompt you to select a category (backend, frontend, testing, architecture, general)
+2. Guide you through providing context, lesson, application, and examples
+3. Automatically tag and organize the entry in the appropriate file
+4. Update this index with new tags and recent entries
+
+---
+
+## 🎯 Best Practices
+
+1. **Be Specific** - Include file paths, class names, method signatures
+2. **Be Actionable** - Provide clear steps for applying the lesson
+3. **Use Examples** - Show before/after code when possible
+4. **Tag Liberally** - Use 3-5 relevant tags per entry for better discoverability
+5. **Capture Immediately** - Record learnings right after discovery while context is fresh
+6. **Review Regularly** - Revisit old learnings to validate or update them
+
+---
+
+## 🤝 Team Collaboration
+
+If using Sublation-OS in a team:
+- Consider keeping memory files in version control to share learnings
+- Review and discuss learnings during code reviews
+- Use consistent tagging conventions across the team
+- Archive or deprecate outdated learnings periodically
+
+See [MEMORY_GUIDE.md](MEMORY_GUIDE.md) for detailed documentation on using the memory system.

package/.sublation-os/memory/learned-lessons.md

@@ -0,0 +1,75 @@
+# Learned Lessons
+
+This file contains durable learnings from Claude Code sessions to help future sessions work more effectively on this codebase.
+
+**Search tips:**
+- Use Ctrl+F to find specific services or patterns
+- Look for 🏷️ Tags sections to find related lessons
+- Entries are chronological - recent ones are at the bottom
+
+---
+
+## Entry Template
+
+### 🧠 Context
+Describe the situation or problem that led to this learning. What were you trying to accomplish?
+
+### 📘 Lesson
+The key insight or principle learned. What should future Claude sessions remember?
+
+### ⚙️ Application
+How to apply this lesson in practice. Specific steps or guidelines.
+
+### 🧩 Example (Optional)
+Code examples showing the right and wrong way:
+
+**❌ Wrong:**
+```language
+// Anti-pattern code
+```
+
+**✅ Correct:**
+```language
+// Better approach
+```
+
+### 🏷️ Tags
+`#tag1` `#tag2` `#tag3`
+
+---
+
+## Example Entry - 2025-01-01 12:00
+
+### 🧠 Context
+When implementing a new feature that required database queries, the initial implementation was loading too much data into memory, causing performance issues.
+
+### 📘 Lesson
+Always use pagination and projection when querying large datasets. Fetch only the fields you need, and limit the number of records returned in a single query.
+
+### ⚙️ Application
+1. Use `Select()` to project to DTOs with only required fields
+2. Use `Skip()` and `Take()` for pagination
+3. Add indexes on frequently filtered columns
+4. Monitor query execution time in development
+
+### 🧩 Example
+**❌ Wrong - loads all entities:**
+```csharp
+var items = dbContext.Items.ToList();
+```
+
+**✅ Correct - paginated with projection:**
+```csharp
+var items = dbContext.Items
+    .Select(i => new ItemDto { Id = i.Id, Name = i.Name })
+    .Skip(pageNumber * pageSize)
+    .Take(pageSize)
+    .ToList();
+```
+
+### 🏷️ Tags
+`#performance` `#database` `#pagination`
+
+---
+
+*Add your own learned lessons below this line. Each entry should follow the template above.*

package/.sublation-os/memory/testing-lessons.md

@@ -0,0 +1,41 @@
+# Testing Lessons
+
+This file contains learnings specific to testing strategies, test frameworks, mocking, and quality assurance.
+
+**Search tips:**
+- Use Ctrl+F to find specific patterns or technologies
+- Look for 🏷️ Tags sections to find related lessons
+- Entries are chronological - recent ones are at the bottom
+
+---
+
+## Entry Template
+
+### 🧠 Context
+Describe the situation or problem that led to this learning. What were you trying to accomplish?
+
+### 📘 Lesson
+The key insight or principle learned. What should future Claude sessions remember?
+
+### ⚙️ Application
+How to apply this lesson in practice. Specific steps or guidelines.
+
+### 🧩 Example (Optional)
+Code examples showing the right and wrong way:
+
+**❌ Wrong:**
+```language
+// Anti-pattern code
+```
+
+**✅ Correct:**
+```language
+// Better approach
+```
+
+### 🏷️ Tags
+`#tag1` `#tag2` `#tag3`
+
+---
+
+*Add testing-specific learned lessons below this line.*

package/.sublation-os/standards/backend/api.md

@@ -0,0 +1,10 @@
+## API endpoint standards and conventions
+
+- **RESTful Design**: Follow REST principles with clear resource-based URLs and appropriate HTTP methods (GET, POST, PUT, PATCH, DELETE)
+- **Consistent Naming**: Use consistent, lowercase, hyphenated or underscored naming conventions for endpoints across the API
+- **Versioning**: Implement API versioning strategy (URL path or headers) to manage breaking changes without disrupting existing clients
+- **Plural Nouns**: Use plural nouns for resource endpoints (e.g., `/users`, `/products`) for consistency
+- **Nested Resources**: Limit nesting depth to 2-3 levels maximum to keep URLs readable and maintainable
+- **Query Parameters**: Use query parameters for filtering, sorting, pagination, and search rather than creating separate endpoints
+- **HTTP Status Codes**: Return appropriate, consistent HTTP status codes that accurately reflect the response (200, 201, 400, 404, 500, etc.)
+- **Rate Limiting Headers**: Include rate limit information in response headers to help clients manage their usage

package/.sublation-os/standards/backend/migrations.md

@@ -0,0 +1,9 @@
+## Database migration best practices
+
+- **Reversible Migrations**: Always implement rollback/down methods to enable safe migration reversals
+- **Small, Focused Changes**: Keep each migration focused on a single logical change for clarity and easier troubleshooting
+- **Zero-Downtime Deployments**: Consider deployment order and backwards compatibility for high-availability systems
+- **Separate Schema and Data**: Keep schema changes separate from data migrations for better rollback safety
+- **Index Management**: Create indexes on large tables carefully, using concurrent options when available to avoid locks
+- **Naming Conventions**: Use clear, descriptive names that indicate what the migration does
+- **Version Control**: Always commit migrations to version control and never modify existing migrations after deployment

package/.sublation-os/standards/backend/models.md

@@ -0,0 +1,10 @@
+## Database model best practices
+
+- **Clear Naming**: Use singular names for models and plural for tables following your framework's conventions
+- **Timestamps**: Include created and updated timestamps on all tables for auditing and debugging
+- **Data Integrity**: Use database constraints (NOT NULL, UNIQUE, foreign keys) to enforce data rules at the database level
+- **Appropriate Data Types**: Choose data types that match the data's purpose and size requirements
+- **Indexes on Foreign Keys**: Index foreign key columns and other frequently queried fields for performance
+- **Validation at Multiple Layers**: Implement validation at both model and database levels for defense in depth
+- **Relationship Clarity**: Define relationships clearly with appropriate cascade behaviors and naming conventions
+- **Avoid Over-Normalization**: Balance normalization with practical query performance needs

package/.sublation-os/standards/backend/queries.md

@@ -0,0 +1,9 @@
+## Database query best practices
+
+- **Prevent SQL Injection**: Always use parameterized queries or ORM methods; never interpolate user input into SQL strings
+- **Avoid N+1 Queries**: Use eager loading or joins to fetch related data in a single query instead of multiple queries
+- **Select Only Needed Data**: Request only the columns you need rather than using SELECT * for better performance
+- **Index Strategic Columns**: Index columns used in WHERE, JOIN, and ORDER BY clauses for query optimization
+- **Use Transactions for Related Changes**: Wrap related database operations in transactions to maintain data consistency
+- **Set Query Timeouts**: Implement timeouts to prevent runaway queries from impacting system performance
+- **Cache Expensive Queries**: Cache results of complex or frequently-run queries when appropriate

package/.sublation-os/standards/frontend/accessibility.md

@@ -0,0 +1,10 @@
+## UI accessibility best practices
+
+- **Semantic HTML**: Use appropriate HTML elements (nav, main, button, etc.) that convey meaning to assistive technologies
+- **Keyboard Navigation**: Ensure all interactive elements are accessible via keyboard with visible focus indicators
+- **Color Contrast**: Maintain sufficient contrast ratios (4.5:1 for normal text) and don't rely solely on color to convey information
+- **Alternative Text**: Provide descriptive alt text for images and meaningful labels for all form inputs
+- **Screen Reader Testing**: Test and verify that all views are accessible on screen reading devices.
+- **ARIA When Needed**: Use ARIA attributes to enhance complex components when semantic HTML isn't sufficient
+- **Logical Heading Structure**: Use heading levels (h1-h6) in proper order to create a clear document outline
+- **Focus Management**: Manage focus appropriately in dynamic content, modals, and single-page applications

package/.sublation-os/standards/frontend/components.md

@@ -0,0 +1,11 @@
+## UI component best practices
+
+- **Single Responsibility**: Each component should have one clear purpose and do it well
+- **Reusability**: Design components to be reused across different contexts with configurable props
+- **Composability**: Build complex UIs by combining smaller, simpler components rather than monolithic structures
+- **Clear Interface**: Define explicit, well-documented props with sensible defaults for ease of use
+- **Encapsulation**: Keep internal implementation details private and expose only necessary APIs
+- **Consistent Naming**: Use clear, descriptive names that indicate the component's purpose and follow team conventions
+- **State Management**: Keep state as local as possible; lift it up only when needed by multiple components
+- **Minimal Props**: Keep the number of props manageable; if a component needs many props, consider composition or splitting it
+- **Documentation**: Document component usage, props, and provide examples for easier adoption by team members

package/.sublation-os/standards/frontend/css.md

@@ -0,0 +1,7 @@
+## CSS best practices
+
+- **Consistent Methodology**: Apply and stick to the project's consistent CSS methodology (Tailwind, BEM, utility classes, CSS modules, etc.) across the entire project
+- **Avoid Overriding Framework Styles**: Work with your framework's patterns rather than fighting against them with excessive overrides
+- **Maintain Design System**: Establish and document design tokens (colors, spacing, typography) for consistency
+- **Minimize Custom CSS**: Leverage framework utilities and components to reduce custom CSS maintenance burden
+- **Performance Considerations**: Optimize for production with CSS purging/tree-shaking to remove unused styles

package/.sublation-os/standards/frontend/responsive.md

@@ -0,0 +1,11 @@
+## Responsive design best practices
+
+- **Mobile-First Development**: Start with mobile layout and progressively enhance for larger screens
+- **Standard Breakpoints**: Consistently use standard breakpoints across the application (e.g., mobile, tablet, desktop)
+- **Fluid Layouts**: Use percentage-based widths and flexible containers that adapt to screen size
+- **Relative Units**: Prefer rem/em units over fixed pixels for better scalability and accessibility
+- **Test Across Devices**: Test and verify UI changes across multiple screen sizes from mobile to tablet to desktop screen sizes and ensure a balanced, user-friendly viewing and reading experience on all
+- **Touch-Friendly Design**: Ensure tap targets are appropriately sized (minimum 44x44px) for mobile users
+- **Performance on Mobile**: Optimize images and assets for mobile network conditions and smaller screens
+- **Readable Typography**: Maintain readable font sizes across all breakpoints without requiring zoom
+- **Content Priority**: Show the most important content first on smaller screens through thoughtful layout decisions

package/.sublation-os/standards/global/coding-style.md

@@ -0,0 +1,10 @@
+## Coding style best practices
+
+- **Consistent Naming Conventions**: Establish and follow naming conventions for variables, functions, classes, and files across the codebase
+- **Automated Formatting**: Maintain consistent code style (indenting, line breaks, etc.)
+- **Meaningful Names**: Choose descriptive names that reveal intent; avoid abbreviations and single-letter variables except in narrow contexts
+- **Small, Focused Functions**: Keep functions small and focused on a single task for better readability and testability
+- **Consistent Indentation**: Use consistent indentation (spaces or tabs) and configure your editor/linter to enforce it
+- **Remove Dead Code**: Delete unused code, commented-out blocks, and imports rather than leaving them as clutter
+- **Backward compatability only when required:** Unless specifically instructed otherwise, assume you do not need to write additional code logic to handle backward compatability.
+- **DRY Principle**: Avoid duplication by extracting common logic into reusable functions or modules

package/.sublation-os/standards/global/commenting.md

@@ -0,0 +1,5 @@
+## Code commenting best practices
+
+- **Self-Documenting Code**: Write code that explains itself through clear structure and naming
+- **Minimal, helpful comments**: Add concise, minimal comments to explain large sections of code logic.
+- **Don't comment changes or fixes**: Do not leave code comments that speak to recent or temporary changes or fixes. Comments should be evergreen informational texts that are relevant far into the future.

package/.sublation-os/standards/global/conventions.md

@@ -0,0 +1,11 @@
+## General development conventions
+
+- **Consistent Project Structure**: Organize files and directories in a predictable, logical structure that team members can navigate easily
+- **Clear Documentation**: Maintain up-to-date README files with setup instructions, architecture overview, and contribution guidelines
+- **Version Control Best Practices**: Use clear commit messages, feature branches, and meaningful pull/merge requests with descriptions
+- **Environment Configuration**: Use environment variables for configuration; never commit secrets or API keys to version control
+- **Dependency Management**: Keep dependencies up-to-date and minimal; document why major dependencies are used
+- **Code Review Process**: Establish a consistent code review process with clear expectations for reviewers and authors
+- **Testing Requirements**: Define what level of testing is required before merging (unit tests, integration tests, etc.)
+- **Feature Flags**: Use feature flags for incomplete features rather than long-lived feature branches
+- **Changelog Maintenance**: Keep a changelog or release notes to track significant changes and improvements

package/.sublation-os/standards/global/error-handling.md

@@ -0,0 +1,9 @@
+## Error handling best practices
+
+- **User-Friendly Messages**: Provide clear, actionable error messages to users without exposing technical details or security information
+- **Fail Fast and Explicitly**: Validate input and check preconditions early; fail with clear error messages rather than allowing invalid state
+- **Specific Exception Types**: Use specific exception/error types rather than generic ones to enable targeted handling
+- **Centralized Error Handling**: Handle errors at appropriate boundaries (controllers, API layers) rather than scattering try-catch blocks everywhere
+- **Graceful Degradation**: Design systems to degrade gracefully when non-critical services fail rather than breaking entirely
+- **Retry Strategies**: Implement exponential backoff for transient failures in external service calls
+- **Clean Up Resources**: Always clean up resources (file handles, connections) in finally blocks or equivalent mechanisms

package/.sublation-os/standards/global/tech-stack.md

@@ -0,0 +1,31 @@
+## Tech stack
+
+Define your technical stack below. This serves as a reference for all team members and helps maintain consistency across the project.
+
+### Framework & Runtime
+- **Application Framework:** [e.g., Rails, Django, Next.js, Express]
+- **Language/Runtime:** [e.g., Ruby, Python, Node.js, Java]
+- **Package Manager:** [e.g., bundler, pip, npm, yarn]
+
+### Frontend
+- **JavaScript Framework:** [e.g., React, Vue, Svelte, Alpine, vanilla JS]
+- **CSS Framework:** [e.g., Tailwind CSS, Bootstrap, custom]
+- **UI Components:** [e.g., shadcn/ui, Material UI, custom library]
+
+### Database & Storage
+- **Database:** [e.g., PostgreSQL, MySQL, MongoDB]
+- **ORM/Query Builder:** [e.g., ActiveRecord, Prisma, Sequelize]
+- **Caching:** [e.g., Redis, Memcached]
+
+### Testing & Quality
+- **Test Framework:** [e.g., Jest, RSpec, pytest]
+- **Linting/Formatting:** [e.g., ESLint, Prettier, RuboCop]
+
+### Deployment & Infrastructure
+- **Hosting:** [e.g., Heroku, AWS, Vercel, Railway]
+- **CI/CD:** [e.g., GitHub Actions, CircleCI]
+
+### Third-Party Services
+- **Authentication:** [e.g., Auth0, Devise, NextAuth]
+- **Email:** [e.g., SendGrid, Postmark]
+- **Monitoring:** [e.g., Sentry, Datadog]

package/.sublation-os/standards/global/validation.md

@@ -0,0 +1,11 @@
+## Validation best practices
+
+- **Validate on Server Side**: Always validate on the server; never trust client-side validation alone for security or data integrity
+- **Client-Side for UX**: Use client-side validation to provide immediate user feedback, but duplicate checks server-side
+- **Fail Early**: Validate input as early as possible and reject invalid data before processing
+- **Specific Error Messages**: Provide clear, field-specific error messages that help users correct their input
+- **Allowlists Over Blocklists**: When possible, define what is allowed rather than trying to block everything that's not
+- **Type and Format Validation**: Check data types, formats, ranges, and required fields systematically
+- **Sanitize Input**: Sanitize user input to prevent injection attacks (SQL, XSS, command injection)
+- **Business Rule Validation**: Validate business rules (e.g., sufficient balance, valid dates) at the appropriate application layer
+- **Consistent Validation**: Apply validation consistently across all entry points (web forms, API endpoints, background jobs)

package/.sublation-os/standards/testing/test-writing.md

@@ -0,0 +1,9 @@
+## Test coverage best practices
+
+- **Write Minimal Tests During Development**: Do NOT write tests for every change or intermediate step. Focus on completing the feature implementation first, then add strategic tests only at logical completion points
+- **Test Only Core User Flows**: Write tests exclusively for critical paths and primary user workflows. Skip writing tests for non-critical utilities and secondary workflows until if/when you're instructed to do so.
+- **Defer Edge Case Testing**: Do NOT test edge cases, error states, or validation logic unless they are business-critical. These can be addressed in dedicated testing phases, not during feature development.
+- **Test Behavior, Not Implementation**: Focus tests on what the code does, not how it does it, to reduce brittleness
+- **Clear Test Names**: Use descriptive names that explain what's being tested and the expected outcome
+- **Mock External Dependencies**: Isolate units by mocking databases, APIs, file systems, and other external services
+- **Fast Execution**: Keep unit tests fast (milliseconds) so developers run them frequently during development

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sublation-OS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# Sublation-OS Framework
+
+A comprehensive development framework for Claude Code that enhances your AI-assisted development workflow with standards, specifications, memory, and powerful agents.
+
+## What is Sublation-OS?
+
+Sublation-OS is a framework that supercharges your Claude Code experience by providing:
+
+- **📚 Standards Library**: Coding conventions, API design patterns, testing practices, and more
+- **📋 Specification System**: Structured approach to feature planning with requirements, tasks, and verification
+- **🧠 Memory System**: Durable learnings that persist across Claude Code sessions
+- **🤖 Specialized Agents**: 7 powerful agents for implementing, verifying, and planning features
+- **⚡ Slash Commands**: Quick commands for common workflows
+
+## Quick Start
+
+### Installation
+
+Install Sublation-OS in your project with a single command:
+
+```bash
+npx sublation-os
+```
+
+That's it! The framework will be installed in your current directory.
+
+For alternative installation methods (script installation, git submodules), see the [Installation Guide](INSTALL.md).
+
+### What Gets Installed
+
+The installer will create/update these directories in your project:
+
+```
+your-project/
+├── .sublation-os/           # Framework core
+│   ├── config.yml           # Configuration
+│   ├── memory/              # Learned lessons
+│   ├── specs/               # Feature specifications
+│   └── standards/           # Coding standards
+├── .claude/
+│   ├── agents/sublation-os/ # 7 specialized agents
+│   └── commands/sublation-os/ # Slash commands
+```
+
+## Features
+
+### Standards Library
+
+15 comprehensive standards files covering:
+- Backend development (API design, error handling, security)
+- Frontend development (UI/UX, state management, accessibility)
+- Data & Testing (database, testing practices)
+- DevOps & Documentation
+
+Customize these for your tech stack to give Claude Code consistent guidance.
+
+### Specification Workflow
+
+Create structured specifications for new features:
+
+1. **Initialize**: Use the spec-initializer agent to create a new spec
+2. **Plan**: Define requirements, create task lists, gather visuals
+3. **Implement**: Follow the task list with the implementer agent
+4. **Verify**: Ensure end-to-end functionality with verification agent
+
+### Memory System
+
+Capture durable learnings from each session:
+- Anti-patterns discovered
+- Performance optimizations
+- Architecture decisions
+- Gotchas and edge cases
+
+Claude Code automatically loads these lessons in future sessions.
+
+### Slash Commands
+
+Quick access to common workflows:
+
+- `/sublation-os:learn` - Capture a learning
+- `/sublation-os:plan-product` - Create product documentation
+- `/sublation-os:create-tasks` - Generate task list from spec
+- `/sublation-os:implement-tasks` - Implement tasks from spec
+- `/sublation-os:commit-message` - Generate git commit message
+- `/sublation-os:review` - Code review
+- `/sublation-os:pr-description` - Generate PR description
+
+## Documentation
+
+- [Installation Guide](INSTALL.md) - Detailed installation options
+- [Setup Guide](docs/setup-guide.md) - First-time setup and customization
+- [Updating Guide](docs/updating.md) - How to update the framework
+- [Agents & Commands](docs/agents-and-commands.md) - Using the specialized agents
+- [Customizing Standards](docs/customizing-standards.md) - Adapting to your tech stack
+
+## Philosophy
+
+Sublation-OS is inspired by the philosophical concept of *Aufheben* (sublation) - the idea of preserving and transcending knowledge. Each development session builds on learnings from previous sessions, creating a continuously improving development experience.
+
+## Requirements
+
+- [Claude Code](https://claude.ai/claude-code) - AI-powered CLI development tool
+- [Node.js](https://nodejs.org/) (version 14 or higher) - For npx installation
+- Git (optional, for submodule installation)
+
+## Updating
+
+Sublation-OS separates framework files (commands, agents) from your project data (memory, standards, specs). Updates only replace framework files while preserving your data.
+
+**Using npx (Recommended):**
+
+Simply run the installer again to update to the latest version:
+
+```bash
+npx sublation-os@latest
+```
+
+The installer will detect your existing installation, create a backup, and update to the latest version.
+
+**Using the update scripts:**
+
+Linux/Mac:
+```bash
+./update-framework.sh
+```
+
+Windows:
+```powershell
+.\update-framework.ps1
+```
+
+**Manual update:**
+```bash
+# Clone the latest version
+git clone https://github.com/nicolosaullo/sublation-os.git /tmp/sublation-os-update
+
+# Update framework files only
+rm -rf .claude/commands/sublation-os .claude/agents/sublation-os
+cp -r /tmp/sublation-os-update/.claude/commands/sublation-os .claude/commands/
+cp -r /tmp/sublation-os-update/.claude/agents/sublation-os .claude/agents/
+```
+
+Your `.sublation-os/` directory (memory, standards, specs) remains untouched.
+
+## Contributing
+
+Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Credits
+
+Created to enhance Claude Code development workflows. Built with love for developers who want their AI assistant to remember and improve.