aether-colony 5.0.0 → 5.2.1

package/.aether/skills/domain/prisma/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: prisma
+description: Use when the project uses Prisma ORM for database access
+type: domain
+domains: [database, orm, schema]
+agent_roles: [builder]
+detect_files: ["schema.prisma"]
+detect_packages: ["@prisma/client"]
+priority: normal
+version: "1.0"
+---
+
+# Prisma Best Practices
+
+## Schema Definition
+
+Define your data model in `schema.prisma` using clear, singular model names (`User`, not `Users`). Prisma generates the table names. Use `@id` with `@default(autoincrement())` or `@default(uuid())` for primary keys.
+
+Add `@map` and `@@map` annotations when table or column names must differ from model names (e.g., mapping to an existing database). Use `@relation` explicitly for clarity, even when Prisma could infer it.
+
+Define enums in the schema for fields with a fixed set of values. This provides type safety across the application.
+
+## Migrations
+
+Run `prisma migrate dev` in development to create and apply migrations. Run `prisma migrate deploy` in production -- it never prompts or resets. Never run `migrate dev` in production.
+
+Review generated migration SQL before applying. Prisma generates migrations in `prisma/migrations/` -- each is a timestamped directory with a SQL file. Edit the SQL if you need data transformations alongside schema changes, but annotate why.
+
+## Client Usage
+
+Generate the client with `prisma generate` after schema changes. Import `PrismaClient` and create a single instance -- reuse it across your application. In serverless environments, store the client in a global variable to avoid connection exhaustion.
+
+```
+// Correct: single instance
+const prisma = new PrismaClient();
+export default prisma;
+```
+
+## Querying
+
+Use `select` to fetch only the fields you need -- avoid loading entire records when you need two columns. Use `include` for relations, but be deliberate about depth. Nested includes can generate expensive joins.
+
+Use `findUnique` when querying by unique fields (id, email) and `findFirst`/`findMany` for non-unique queries. Prefer `findUniqueOrThrow` when the record must exist.
+
+## Performance Gotchas
+
+Avoid N+1 queries by using `include` in a single query rather than looping and querying per item. Use `createMany` for bulk inserts instead of looping `create` calls.
+
+For large datasets, use cursor-based pagination: `findMany({ take: 20, skip: 1, cursor: { id: lastId } })`. Offset pagination degrades on large tables.
+
+Raw queries via `$queryRaw` are available when Prisma's query builder is insufficient, but use parameterized templates (`Prisma.sql`) to prevent injection.
+
+## Type Safety
+
+Prisma generates TypeScript types from your schema. Use `Prisma.UserCreateInput`, `Prisma.UserWhereInput`, etc. for type-safe function parameters. Never bypass these types with `any` -- they catch schema mismatches at compile time.
+
+## Seeding
+
+Define seed scripts in `prisma/seed.ts` and register them in `package.json` under `prisma.seed`. Use `upsert` in seeds to make them idempotent -- running the seed twice should not create duplicates.

package/.aether/skills/domain/python/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: python
+description: Use when the project uses Python for backend, scripting, or data work
+type: domain
+domains: [backend, scripting, data]
+agent_roles: [builder]
+detect_files: ["*.py", "requirements.txt", "pyproject.toml"]
+priority: normal
+version: "1.0"
+---
+
+# Python Best Practices
+
+## Project Setup
+
+Use virtual environments for every project -- never install packages globally. Prefer `pyproject.toml` over `setup.py` for project configuration. Pin dependency versions in `requirements.txt` or use a lock file via `pip-tools`, `poetry`, or `uv`.
+
+Structure packages with `__init__.py` files. Use `src/` layout for libraries to prevent accidental imports from the project root.
+
+## Code Style
+
+Follow PEP 8. Use a formatter (black, ruff format) and linter (ruff, flake8) -- do not manually enforce style. Type hints are strongly encouraged for function signatures and return values. Use `mypy` or `pyright` for type checking.
+
+Use f-strings for string formatting, not `%` or `.format()`. They are faster and more readable.
+
+## Error Handling
+
+Catch specific exceptions, never bare `except:`. This swallows `KeyboardInterrupt` and `SystemExit`, making the program impossible to stop. Always `except SomeError as e:` and log or re-raise.
+
+Use context managers (`with` statements) for resource management: files, database connections, locks. They guarantee cleanup even when exceptions occur.
+
+## Functions and Classes
+
+Keep functions focused and short. Use keyword arguments for functions with more than 3 parameters to avoid positional ambiguity. Provide default values where sensible.
+
+Prefer composition over deep inheritance hierarchies. Dataclasses (`@dataclass`) or named tuples for simple data containers -- avoid dictionaries when the shape is known.
+
+## Common Gotchas
+
+Mutable default arguments are shared across calls: `def f(items=[])` is a bug. Use `def f(items=None): items = items or []` instead.
+
+String concatenation in loops is O(n^2). Use `"".join(parts)` or list comprehensions. List comprehensions are preferred over `map`/`filter` for readability.
+
+## Testing
+
+Use `pytest` over `unittest`. Write test files with `test_` prefix. Use fixtures for setup/teardown. Parametrize tests with `@pytest.mark.parametrize` to cover multiple cases without duplicating test code.
+
+## Performance
+
+Profile before optimizing -- use `cProfile` or `py-spy`. For CPU-bound work, consider `multiprocessing` (the GIL prevents true threading for CPU tasks). For I/O-bound work, use `asyncio` or `concurrent.futures.ThreadPoolExecutor`.

package/.aether/skills/domain/rails/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: rails
+description: Use when the project uses Ruby on Rails for web development
+type: domain
+domains: [backend, ruby, web]
+agent_roles: [builder]
+detect_files: ["Gemfile", "config/routes.rb"]
+priority: normal
+version: "1.0"
+---
+
+# Ruby on Rails Best Practices
+
+## Convention Over Configuration
+
+Follow Rails conventions strictly. Name models singular (`User`), controllers plural (`UsersController`), tables plural (`users`). Place files where Rails expects them. Fighting conventions creates maintenance headaches.
+
+Use Rails generators for scaffolding, then customize. They set up the correct file structure, naming, and test stubs.
+
+## Models
+
+Keep models focused. Move business logic into service objects or concerns when a model exceeds 200 lines. Use Active Record validations for data integrity and callbacks sparingly -- callbacks that trigger side effects (emails, API calls) are better handled in service objects.
+
+Use scopes for reusable query patterns: `scope :active, -> { where(active: true) }`. Chain scopes for composable queries.
+
+## Controllers
+
+Keep controllers thin. A controller action should: authenticate, authorize, call a service, and render a response. Complex logic belongs in service objects (`app/services/`), not controllers.
+
+Use strong parameters (`params.require(:user).permit(:name, :email)`) for every create/update action. Never trust user input.
+
+## Database
+
+Write migrations for every schema change -- never modify the database manually. Use `change` methods in migrations for reversibility. Add database-level constraints (NOT NULL, unique indexes, foreign keys) alongside Active Record validations.
+
+Watch for N+1 queries. Use `includes()` for eager loading associations. The `bullet` gem detects N+1 queries in development.
+
+## Testing
+
+Write request specs over controller specs -- they test the full stack including routing and middleware. Use `FactoryBot` for test data, not fixtures (fixtures become stale and hard to maintain).
+
+Test the happy path and the most important failure modes. Use `let` and `before` blocks in RSpec for DRY test setup, but do not over-abstract -- tests should be readable as documentation.
+
+## Security
+
+Never store secrets in source code. Use Rails encrypted credentials (`rails credentials:edit`) or environment variables. Keep `secret_key_base` secure -- it signs session cookies.
+
+Sanitize user-generated HTML output. Rails escapes by default in ERB, but `raw` and `html_safe` bypass this -- use them only with trusted content.
+
+## Performance
+
+Cache aggressively with fragment caching and Russian doll caching. Use background jobs (Sidekiq, GoodJob) for anything that takes more than a few hundred milliseconds -- email delivery, API calls, report generation.

package/.aether/skills/domain/react/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: react
+description: Use when the project uses React for building user interfaces
+type: domain
+domains: [frontend, components, ui]
+agent_roles: [builder]
+detect_files: ["*.jsx", "*.tsx"]
+detect_packages: ["react"]
+priority: normal
+version: "1.0"
+---
+
+# React Best Practices
+
+## Component Design
+
+Prefer function components with hooks over class components. Keep components small and focused on a single responsibility. If a component file exceeds 200 lines, it likely needs splitting.
+
+Extract custom hooks when you find yourself reusing stateful logic across components. Name hooks with the `use` prefix and keep them in a dedicated `hooks/` directory.
+
+## State Management
+
+Use `useState` for local UI state, `useReducer` for complex state transitions, and context for cross-cutting concerns like themes or auth. Avoid putting everything in global state -- most state is local.
+
+Lift state up only when two sibling components need the same data. If prop drilling goes deeper than 2-3 levels, consider context or composition patterns instead.
+
+## Performance Gotchas
+
+Wrap expensive computations in `useMemo` and callback references in `useCallback`, but only when you measure an actual performance problem. Premature memoization adds complexity without benefit.
+
+Never create new objects or arrays inline as props -- this triggers unnecessary re-renders. Define defaults outside the component body.
+
+Avoid anonymous functions in `useEffect` dependency arrays. Extract effect logic into named functions for clarity and stable references.
+
+## Keys and Lists
+
+Always use stable, unique identifiers as keys in lists -- never array indices (unless the list is static and will never reorder). Bad keys cause subtle bugs with component state getting mixed up between items.
+
+## Error Boundaries
+
+Wrap major UI sections in error boundaries. A crash in a sidebar widget should not take down the entire page. Use `react-error-boundary` or build your own class component for this.
+
+## File Organization
+
+Group by feature, not by type. Colocate a component with its tests, styles, and hooks rather than having separate `components/`, `styles/`, and `tests/` trees. This makes features self-contained and easy to move or delete.

package/.aether/skills/domain/rest-api/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: rest-api
+description: Use when the project designs or consumes RESTful HTTP APIs
+type: domain
+domains: [api, http, design]
+agent_roles: [builder]
+detect_files: ["openapi.*", "swagger.*"]
+priority: normal
+version: "1.0"
+---
+
+# REST API Best Practices
+
+## Resource Design
+
+Use nouns for endpoints, not verbs: `/users` not `/getUsers`. Let HTTP methods convey the action: `GET` (read), `POST` (create), `PUT` (full replace), `PATCH` (partial update), `DELETE` (remove).
+
+Use plural nouns for collections (`/users`), singular identifiers for items (`/users/123`). Nest resources for clear ownership: `/users/123/orders` for orders belonging to user 123. Avoid nesting deeper than two levels -- flatten with query parameters instead.
+
+## HTTP Status Codes
+
+Return the correct status code -- clients depend on it for error handling:
+- `200` for successful GET/PUT/PATCH
+- `201` for successful POST (resource created)
+- `204` for successful DELETE (no content)
+- `400` for bad request (validation errors)
+- `401` for unauthenticated
+- `403` for unauthorized (authenticated but not allowed)
+- `404` for not found
+- `409` for conflict (duplicate, version mismatch)
+- `422` for unprocessable entity (valid JSON, invalid semantics)
+- `500` for server errors (never expose internals)
+
+## Request and Response Format
+
+Use JSON for request and response bodies. Use `camelCase` for JSON field names (JavaScript convention) or `snake_case` (Python convention) -- be consistent within the API, never mix.
+
+Return consistent error responses: `{"error": "message", "code": "VALIDATION_FAILED", "details": [...]}`. Clients should be able to parse errors programmatically, not just read human messages.
+
+## Pagination
+
+Always paginate collection endpoints. Use cursor-based pagination (`?cursor=abc123&limit=20`) for large or frequently changing datasets. Include pagination metadata in the response: `total`, `next_cursor`, `has_more`.
+
+## Versioning
+
+Version your API from day one: `/api/v1/users`. Use URL-based versioning for simplicity. Header-based versioning (`Accept: application/vnd.api.v1+json`) is cleaner but harder to test and debug.
+
+## Authentication
+
+Use bearer tokens (JWT or opaque) in the `Authorization` header. Never pass tokens in URL query parameters -- they appear in logs and browser history. Use short-lived access tokens with refresh tokens for longer sessions.
+
+## Documentation
+
+Maintain an OpenAPI specification (`openapi.yaml`). Generate it from code annotations or write it manually, but keep it in sync with the implementation. Stale API docs are worse than no docs -- they create false confidence.
+
+## Rate Limiting
+
+Implement rate limiting on all public endpoints. Return `429 Too Many Requests` with `Retry-After` header. Use sliding window counters, not fixed windows, to prevent burst abuse at window boundaries.

package/.aether/skills/domain/svelte/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: svelte
+description: Use when the project uses Svelte or SvelteKit for building reactive UIs
+type: domain
+domains: [frontend, components, ui]
+agent_roles: [builder]
+detect_files: ["*.svelte", "svelte.config.*"]
+detect_packages: ["svelte"]
+priority: normal
+version: "1.0"
+---
+
+# Svelte Best Practices
+
+## Reactivity Model
+
+Svelte uses compile-time reactivity. Variables declared at the top level of a component are reactive automatically -- assignments trigger re-renders. Use `$:` for derived values and reactive statements. Remember that only assignments trigger reactivity: `array.push(item)` does NOT trigger updates -- use `array = [...array, item]` instead.
+
+## Component Structure
+
+Keep components focused on one concern. A Svelte component file should ideally contain its own script, markup, and styles. Use `<script>` at the top, markup in the middle, and `<style>` at the bottom.
+
+## Stores
+
+Use writable stores for shared state across components. Subscribe with the `$store` syntax in components for automatic subscription cleanup. For derived data, use `derived()` stores rather than computing values in each component.
+
+Keep stores in a `stores/` directory. Export store creation functions rather than store instances when stores need initialization parameters.
+
+## Props and Events
+
+Declare props with `export let propName`. Provide default values for optional props. Use `createEventDispatcher()` for component events, and forward DOM events with `on:click` without a handler.
+
+Use two-way binding (`bind:value`) sparingly -- it makes data flow harder to trace. Prefer explicit prop + event patterns for complex components.
+
+## SvelteKit Specifics
+
+SvelteKit uses file-based routing in `src/routes/`. Page components are `+page.svelte`, layouts are `+layout.svelte`, and server-side logic lives in `+page.server.ts` or `+server.ts`.
+
+Load data with `load` functions in `+page.ts` (universal) or `+page.server.ts` (server-only). Use form actions for mutations rather than custom API endpoints.
+
+## Styling
+
+Svelte styles are scoped by default -- styles in `<style>` only affect the current component. Use `:global()` modifier cautiously when you need to reach outside component boundaries.
+
+## Performance
+
+Svelte compiles away the framework, so bundles are naturally small. Use `{#key}` blocks to force re-creation of components when data changes identity. Use `{#each}` with keyed items for efficient list updates. Lazy-load heavy components with dynamic imports.

package/.aether/skills/domain/tailwind/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: tailwind
+description: Use when the project uses Tailwind CSS for utility-first styling
+type: domain
+domains: [css, frontend, styling]
+agent_roles: [builder]
+detect_files: ["tailwind.config.*"]
+detect_packages: ["tailwindcss"]
+priority: normal
+version: "1.0"
+---
+
+# Tailwind CSS Best Practices
+
+## Utility-First Approach
+
+Apply styles directly with utility classes rather than writing custom CSS. Resist the urge to create `.btn` or `.card` classes -- use component abstractions in your framework instead (React components, Vue components, partials). Custom CSS should be the exception, not the default.
+
+## Class Organization
+
+Order classes consistently: layout (flex, grid, position) first, then sizing (w, h, p, m), then typography (text, font), then visual (bg, border, shadow), then states (hover, focus). Use Prettier with `prettier-plugin-tailwindcss` to automate class sorting.
+
+When a class list gets long (10+ utilities), extract it into a component rather than using `@apply`. The `@apply` directive defeats the purpose of utility-first and creates hidden CSS that is harder to maintain.
+
+## Responsive Design
+
+Tailwind is mobile-first. Write base styles for mobile, then add responsive modifiers: `sm:`, `md:`, `lg:`, `xl:`. Never start with desktop styles and subtract.
+
+Test responsive behavior at each breakpoint. Use the browser's device toolbar, not just resizing the window.
+
+## Customization
+
+Extend the theme in `tailwind.config.js` rather than using arbitrary values. If you find yourself writing `bg-[#1a2b3c]` more than once, add it to your theme colors. Arbitrary values signal missing design tokens.
+
+Use CSS variables for dynamic values (dark mode, user themes): define variables in your CSS, reference them in the Tailwind config with `var(--color-primary)`.
+
+## Common Gotchas
+
+Tailwind purges unused classes in production. Dynamic class names assembled with string concatenation will be purged because the scanner cannot detect them. Always use complete class names: write `text-red-500` not `text-${color}-500`. Use the `safelist` config option for truly dynamic classes.
+
+Avoid `!important` modifiers (`!text-red-500`) -- they indicate specificity fights that usually mean structural issues. Fix the cascade instead.
+
+## Dark Mode
+
+Use the `dark:` variant with the `class` strategy for manual control, or `media` strategy for OS-level preference. Be consistent across the project -- mixing strategies causes unpredictable behavior.

package/.aether/skills/domain/testing/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: testing
+description: Use when the project needs automated testing with Jest, Vitest, pytest, or similar frameworks
+type: domain
+domains: [testing, quality, tdd]
+agent_roles: [builder]
+detect_files: ["*.test.*", "*.spec.*"]
+detect_packages: ["jest", "vitest", "pytest"]
+priority: normal
+version: "1.0"
+---
+
+# Testing Best Practices
+
+## Test Structure
+
+Follow the Arrange-Act-Assert pattern: set up the conditions, perform the action, check the result. Each test should verify one behavior. If a test name contains "and", it probably tests two things -- split it.
+
+Name tests to describe behavior, not implementation: "returns empty array when no items match filter" not "test filterItems function". Good test names serve as documentation.
+
+## Test-Driven Development
+
+Write the test before the implementation. Start with the simplest failing test, write minimal code to make it pass, then refactor. This cycle (Red-Green-Refactor) prevents over-engineering and ensures every line of production code is covered.
+
+When fixing bugs, write a test that reproduces the bug first. Then fix the code. The test proves the bug existed and prevents regression.
+
+## What to Test
+
+Test behavior, not implementation. Test public interfaces, not private methods. If you refactor internals without changing behavior, tests should still pass. Tests that break during refactoring are testing the wrong thing.
+
+Focus coverage on: business logic, data transformations, error handling paths, edge cases (empty inputs, boundary values, null/undefined). Skip testing: framework boilerplate, simple getters/setters, third-party library behavior.
+
+## Mocking
+
+Mock external dependencies (APIs, databases, file system), not your own code. Over-mocking creates tests that pass even when the real system is broken. Use the lightest mock possible -- spy on a method rather than replacing an entire module.
+
+Reset mocks between tests to prevent state leakage. In Jest/Vitest, use `beforeEach(() => { vi.clearAllMocks() })`. In pytest, fixtures handle cleanup automatically.
+
+## Test Performance
+
+Fast tests get run often. Slow tests get skipped. Keep unit tests under 100ms each. Isolate slow integration tests into a separate suite that runs less frequently.
+
+Avoid `sleep` or timeouts in tests. Use fake timers (`vi.useFakeTimers()`) for time-dependent code. Wait for conditions with polling utilities, not fixed delays.
+
+## Test Organization
+
+Colocate tests with source files (`Button.tsx` next to `Button.test.tsx`) or use a parallel `__tests__/` directory. Be consistent across the project.
+
+Use `describe` blocks to group related tests. Use `it` or `test` for individual cases. Setup shared across a `describe` block goes in `beforeEach`, not duplicated in each test.
+
+## Continuous Integration
+
+Tests must pass before merging. Run the full suite in CI on every pull request. Fail the build on test failures -- never merge with known failures. Aim for meaningful coverage (80%+) over line-count metrics.

package/.aether/skills/domain/typescript/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: typescript
+description: Use when the project uses TypeScript for type-safe JavaScript development
+type: domain
+domains: [typing, language, safety]
+agent_roles: [builder]
+detect_files: ["tsconfig.json", "*.ts"]
+priority: normal
+version: "1.0"
+---
+
+# TypeScript Best Practices
+
+## Configuration
+
+Enable strict mode in `tsconfig.json` (`"strict": true`). This turns on `strictNullChecks`, `noImplicitAny`, `strictFunctionTypes`, and other checks that catch real bugs. Loosening strict mode after the fact is easy; adding it to an existing loose codebase is painful.
+
+Set `"noUncheckedIndexedAccess": true` to make array and object index access return `T | undefined` instead of `T`. This catches a class of runtime errors where you assume an index exists.
+
+## Type Design
+
+Prefer `interface` for object shapes that may be extended. Use `type` for unions, intersections, and computed types. Both work for most cases, but `interface` gives better error messages and supports declaration merging.
+
+Make impossible states unrepresentable. Use discriminated unions instead of optional fields:
+
+```typescript
+// Avoid: what does it mean when both are undefined?
+type Result = { data?: Data; error?: Error };
+
+// Prefer: exactly one state at a time
+type Result = { status: "ok"; data: Data } | { status: "error"; error: Error };
+```
+
+## Avoid These Patterns
+
+Never use `any` -- use `unknown` when the type is truly unknown, then narrow it with type guards. Every `any` disables type checking for everything it touches.
+
+Avoid type assertions (`as Type`) unless you genuinely know more than the compiler. Prefer type guards (`if ('kind' in obj)`) that the compiler can verify.
+
+Do not use `!` (non-null assertion) to silence nullable warnings. Fix the logic so the compiler can see the value is defined, or handle the null case.
+
+## Generics
+
+Use generics to make functions and types reusable without losing type information. Name generic parameters descriptively when the context is not obvious: `TItem` over `T` when there are multiple type parameters.
+
+Constrain generics with `extends` to ensure minimum capability: `<T extends { id: string }>` guarantees `T` has an `id` field.
+
+## Utility Types
+
+Use built-in utility types: `Partial<T>` for optional fields, `Required<T>` for mandatory, `Pick<T, K>` to select fields, `Omit<T, K>` to exclude, `Record<K, V>` for dictionaries. These are clearer than manual type construction.
+
+## Enums
+
+Prefer `as const` objects or string literal unions over `enum`. Enums generate runtime code and have subtle behavior differences between string and numeric variants. `as const` objects are pure types with zero runtime cost.
+
+## Error Handling
+
+Type your error shapes. Define error types and use them in `Result` patterns. Catch blocks receive `unknown` in strict mode -- narrow before accessing properties.

package/.aether/skills/domain/vue/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: vue
+description: Use when the project uses Vue.js for building reactive user interfaces
+type: domain
+domains: [frontend, components, ui]
+agent_roles: [builder]
+detect_files: ["*.vue", "vue.config.*"]
+detect_packages: ["vue"]
+priority: normal
+version: "1.0"
+---
+
+# Vue Best Practices
+
+## Composition API
+
+Prefer the Composition API (`<script setup>`) over the Options API for new code. It provides better TypeScript support, more flexible logic reuse through composables, and cleaner component organization. Check which API the existing codebase uses before introducing the other.
+
+## Reactivity System
+
+Use `ref()` for primitives and `reactive()` for objects. Remember that `reactive()` loses reactivity when destructured -- use `toRefs()` if you need to destructure. Always access `ref` values with `.value` in script, but not in templates.
+
+Avoid replacing an entire `reactive()` object -- mutate its properties instead. Replacing the reference breaks reactivity tracking.
+
+## Composables
+
+Extract reusable logic into composables (functions prefixed with `use`). A composable returns reactive state and methods. Keep composables in a `composables/` directory and each in its own file.
+
+Composables must be called at the top level of `setup()` or `<script setup>`, never inside conditionals or loops.
+
+## Component Communication
+
+Props down, events up. Use `defineProps()` and `defineEmits()` in `<script setup>`. For deeply nested communication, use `provide/inject` rather than prop drilling.
+
+Never mutate props directly. If a child needs to modify parent data, emit an event.
+
+## Performance
+
+Use `v-show` instead of `v-if` for elements that toggle frequently -- `v-show` keeps the DOM node and just toggles CSS display. Use `v-if` for conditional blocks that rarely change.
+
+Add `key` attributes on `v-for` lists using stable unique identifiers, never indices for dynamic lists.
+
+Lazy-load route components with dynamic imports: `() => import('./views/Heavy.vue')`.
+
+## Template Discipline
+
+Keep templates declarative. Complex logic belongs in computed properties, not inline expressions. If a template expression has more than one ternary or logical operator, extract it to a computed.
+
+Use scoped styles (`<style scoped>`) to prevent CSS leaking between components. Use `:deep()` only when you genuinely need to style child component internals.

package/.aether/templates/QUEEN.md.template

@@ -1,79 +1,61 @@
-# QUEEN.md — Colony Wisdom
+# QUEEN.md -- Colony Wisdom
 
 > Last evolved: {TIMESTAMP}
-> Colonies contributed: 0
-> Wisdom version: 1.0.0
+> Wisdom version: 2.0.0
 
 ---
 
-## 📜 Philosophies
+## User Preferences
 
-Core beliefs that guide all colony work. These are validated through repeated successful application across multiple colonies.
+Communication style, expertise level, and decision-making patterns observed from the user (the Queen). These shape how the colony communicates and what it prioritizes. User decisions are the most important wisdom.
 
-*No philosophies recorded yet. Philosophies are promoted from PHILOSOPHY pheromones after 5+ validations.*
+*No user preferences recorded yet.*
 
 ---
 
-## 🧭 Patterns
+## Codebase Patterns
 
-Validated approaches that consistently work. These represent discovered best practices that have proven themselves in the field.
+Validated approaches that work in this codebase, and anti-patterns to avoid. Includes architecture conventions, naming patterns, error handling style, and technology-specific insights. Tagged [repo] for project-specific or [general] for cross-colony patterns.
 
-*No patterns recorded yet. Patterns are promoted from PATTERN pheromones after 3+ validations.*
+*No codebase patterns recorded yet.*
 
 ---
 
-## ⚠️ Redirects
+## Build Learnings
 
-Anti-patterns to avoid. These represent approaches that have caused problems and should be redirected away from.
+What worked and what failed during builds. Captures the full picture of colony experience -- successes, failures, and adjustments. Each entry includes the phase where it was learned.
 
-*No redirects recorded yet. Redirects are promoted from REDIRECT pheromones after 2+ triggers.*
+*No build learnings recorded yet.*
 
 ---
 
-## 🔧 Stack Wisdom
+## Instincts
 
-Technology-specific insights and constraints detected through codebase analysis.
+High-confidence behavioral patterns that have been validated through repeated colony work. Auto-promoted when confidence reaches 0.8 or higher. These represent the colony's deepest learned behaviors.
 
-*No stack wisdom recorded yet. Stack wisdom is auto-populated by `/ant:colonize`.*
+*No instincts recorded yet.*
 
 ---
 
-## 🏛️ Decrees
+## Evolution Log
 
-User-mandated rules that override other guidance. These represent explicit directives from the Queen.
-
-*No decrees recorded yet. Decrees are added via `/ant:decree "<rule>"`.*
-
----
-
-## 📊 Evolution Log
-
-Track how wisdom has evolved over time.
-
-| Date | Colony | Change | Details |
-|------|--------|--------|---------|
+| Date | Source | Type | Details |
+|------|--------|------|---------|
 | {TIMESTAMP} | system | initialized | QUEEN.md created from template |
 
 ---
 
 <!-- METADATA
 {
-  "version": "1.0.0",
+  "version": "2.0.0",
+  "wisdom_version": "2.0",
   "last_evolved": "{TIMESTAMP}",
   "colonies_contributed": [],
-  "promotion_thresholds": {
-    "philosophy": 5,
-    "pattern": 3,
-    "redirect": 2,
-    "stack": 1,
-    "decree": 0
-  },
   "stats": {
-    "total_philosophies": 0,
-    "total_patterns": 0,
-    "total_redirects": 0,
-    "total_stack_entries": 0,
-    "total_decrees": 0
+    "total_user_prefs": 0,
+    "total_codebase_patterns": 0,
+    "total_build_learnings": 0,
+    "total_instincts": 0
   }
 }
 -->

package/.aether/templates/colony-state-reset.jq.template

@@ -3,6 +3,7 @@
 # Version: 1.0
 
 .goal = null |
+.colony_version = 0 |
 .state = "IDLE" |
 .current_phase = 0 |
 .plan.phases = [] |

package/.aether/templates/colony-state.template.json

@@ -3,11 +3,15 @@
   "_version": "3.0",
   "_instructions": "Write this file to .aether/data/COLONY_STATE.json. Replace every __PLACEHOLDER__ value with real data (see _comment_* fields for details). After filling all placeholders, remove every key whose name starts with underscore (_template, _version, _instructions, and all _comment_*) before writing the final file.",
   "_comment_goal": "Replace __GOAL__ with the user's goal string exactly as provided to /ant:init.",
+  "_comment_colony_name": "Set during first charter-write. Human-readable name derived from repo directory or package.json.",
+  "_comment_colony_version": "Integer counter incremented each time the colony is sealed. Starts at 1 on colony initialization. Reset to 0 on entomb (ready for next colony). Tracks how many times this colony has been sealed.",
   "_comment_session": "Replace __SESSION_ID__ with a generated ID in the format: session_{unix_timestamp}_{random}. Replace __ISO8601_TIMESTAMP__ with the current UTC time in ISO-8601 format (e.g., 2026-02-20T00:00:00Z). The same timestamp value is used in both 'initialized_at' and the events array entry.",
   "_comment_memory": "Replace __PHASE_LEARNINGS__ with a JSON array (e.g., [] if no prior colony found, or [{...}, ...] if inherited from completion-report.md). Replace __INSTINCTS__ with a JSON array (e.g., [] or [{...}, ...]). IMPORTANT: both must be JSON arrays, not strings — write [] not \"[]\".",
   "_comment_events": "The events array records colony lifecycle events. Each entry is a pipe-delimited string: 'ISO8601_TIMESTAMP|event_type|source|description'. The initialization event uses the same __ISO8601_TIMESTAMP__ as 'initialized_at'. Do not add extra events during init — the single initialization entry is correct.",
   "version": "3.0",
   "goal": "__GOAL__",
+  "colony_name": null,
+  "colony_version": 1,
   "state": "READY",
   "current_phase": 0,
   "session_id": "__SESSION_ID__",