@ooneex/cli 1.33.1 → 1.33.3

package/dist/index.js

@@ -6533,7 +6533,7 @@ var package_json_default = `{
 `;
 
 // src/templates/app/README.md.txt
-var README_md_default = "# {{NAME}}\n\nA modular, enterprise-grade backend framework built with TypeScript and Bun, powered by the **@ooneex** ecosystem.\n\n## Prerequisites\n\n- [Bun](https://bun.sh) (latest)\n- [Docker](https://www.docker.com/) & Docker Compose\n\n## Getting Started\n\n### Install Dependencies\n\n```bash\nbun install\n```\n\n### Environment Configuration\n\nCopy the environment template and fill in the required values:\n\n```bash\ncp modules/app/.env.example modules/app/.env\n```\n\n| Variable | Description | Required |\n|---|---|---|\n| `APP_ENV` | Application environment (`local`, `development`, `staging`, `testing`, `production`, \u2026) | Yes |\n| `PORT` | Server port number (default: `3000`) | Yes |\n| `HOST_NAME` | Server hostname (default: `0.0.0.0`) | Yes |\n| `CSRF_SECRET` | Secret key for CSRF token generation and verification | Yes |\n| `LOGS_DATABASE_URL` | Database URL for storing application logs | No |\n| `BETTERSTACK_LOGGER_SOURCE_TOKEN` | Logtail source token for Better Stack logging | No |\n| `BETTERSTACK_EXCEPTION_LOGGER_APPLICATION_TOKEN` | Better Stack token for exception tracking | No |\n| `ANALYTICS_POSTHOG_PROJECT_TOKEN` | PostHog API key for event tracking | No |\n| `CACHE_REDIS_URL` | Redis connection URL for caching | No |\n| `CACHE_UPSTASH_REDIS_REST_URL` | Upstash Redis REST URL for serverless caching | No |\n| `PUBSUB_REDIS_URL` | Redis connection URL for pub/sub messaging | No |\n| `RATE_LIMIT_REDIS_URL` | Redis connection URL for rate limiting | No |\n| `CORS_ORIGINS` | Comma-separated allowed origins or `*` (default: `*`) | No |\n| `CORS_METHODS` | Comma-separated HTTP methods | No |\n| `CORS_HEADERS` | Comma-separated allowed request headers | No |\n| `CORS_CREDENTIALS` | Allow credentials: `true` or `false` | No |\n| `DATABASE_URL` | PostgreSQL connection URL | No |\n| `DATABASE_REDIS_URL` | Redis connection URL for Redis-based database operations | No |\n| `SQLITE_DATABASE_PATH` | SQLite database file path | No |\n| `STORAGE_CLOUDFLARE_ACCESS_KEY` | Cloudflare R2 access key ID | No |\n| `STORAGE_CLOUDFLARE_SECRET_KEY` | Cloudflare R2 secret access key | No |\n| `STORAGE_CLOUDFLARE_ENDPOINT` | Cloudflare R2 endpoint URL | No |\n| `STORAGE_BUNNY_ACCESS_KEY` | BunnyCDN access key | No |\n| `STORAGE_BUNNY_STORAGE_ZONE` | BunnyCDN storage zone name | No |\n| `FILESYSTEM_STORAGE_PATH` | Base directory path for local file storage | No |\n| `MAILER_SENDER_NAME` | Display name for email sender | No |\n| `MAILER_SENDER_ADDRESS` | Email address for sender | No |\n| `RESEND_API_KEY` | Resend email service API key | No |\n| `JWT_SECRET` | Secret key for HS256 JWT signing and verification | No |\n| `OPENROUTER_API_KEY` | OpenRouter API key for accessing 300+ AI models | No |\n| `OPENAI_API_KEY` | OpenAI API key | No |\n| `ANTHROPIC_API_KEY` | Anthropic API key for Claude models | No |\n| `GEMINI_API_KEY` | Google Gemini API key | No |\n| `GROQ_API_KEY` | Groq API key for LLM inference | No |\n| `POLAR_ACCESS_TOKEN` | Polar payment platform access token | No |\n| `CLERK_SECRET_KEY` | Clerk authentication secret key | No |\n\n### Start the App\n\nStarts Docker services (if a `docker-compose.yml` is present) and launches the application with hot reload:\n\n```bash\noo app:start\n```\n\n### Stop the App\n\nStops all Docker services:\n\n```bash\noo app:stop\n```\n\n### Build the App\n\nCompiles the application for production. Output is written to the `dist` directory:\n\n```bash\noo app:build\n```\n\n---\n\n## Modules\n\nModules are the core organizational unit. Each module lives under `modules/<name>/` and contains its own controllers, services, repositories, entities, migrations, and seeds.\n\n### Why Modules?\n\nA flat codebase quickly becomes hard to navigate and reason about as an application grows. Modules address this by enforcing **vertical slicing**: all code related to a single business domain (e.g. `user`, `order`, `billing`) lives together rather than being scattered across generic `controllers/`, `services/`, and `repositories/` folders.\n\n**Benefits:**\n\n- **Domain isolation** \u2014 changes to one feature cannot accidentally break another; each module is a self-contained unit with explicit boundaries.\n- **Parallel development** \u2014 teams can work on separate modules without stepping on each other's code or creating merge conflicts in shared directories.\n- **Independent deployment** \u2014 a module can be extracted into a standalone service later with minimal refactoring because its code is already co-located.\n- **Simpler onboarding** \u2014 a new developer understands the scope of a feature by exploring a single directory instead of tracing imports across the whole project.\n- **Scoped migrations & seeds** \u2014 database changes stay close to the entities they affect, making rollbacks and reviews straightforward.\n\n**Good practices:**\n\n- Name modules after business domains (`user`, `product`, `payment`), not technical layers (`controllers`, `helpers`).\n- Keep modules small and focused. If a module grows beyond ~10 controllers or services, consider splitting it by sub-domain.\n- Never import from another module's internal files directly \u2014 expose only what is needed through the module's public index.\n- Register all entities in `SharedModule` (done automatically by `oo make:entity`) so the ORM has a single source of truth.\n- Run `oo module:lock` after every migration or seed change to protect file integrity in CI.\n- Prefix route names with the module name (e.g. `api.user.create`) to avoid collisions across modules.\n\n### Create a Module\n\nScaffolds a new module with all required structure, registers it in `AppModule`, adds its entities to `SharedModule`, and updates `tsconfig.json` path aliases and commitlint config:\n\n```bash\noo module:create\noo module:create --name user\n```\n\n### Lock a Module\n\nHashes migration and seed files into a module manifest (`.yml`) for integrity verification. Run this after adding or modifying migrations/seeds:\n\n```bash\noo module:lock --module user\noo module:lock --module user --override   # force update existing hashes\n```\n\n### Delete a Module\n\nRemoves a module and cleans up all references from `AppModule`, `SharedModule`, `tsconfig.json`, and commitlint config. The `app` and `shared` core modules cannot be removed:\n\n```bash\noo module:remove\noo module:remove --name user\noo module:remove --name user --silent    # skip confirmation prompt\n```\n\n---\n\n## Migrations\n\nMigrations are versioned, incremental SQL scripts that evolve your database schema over time. Each migration lives in `modules/<name>/src/migrations/` and is executed in order, making every schema change reproducible, reviewable, and reversible.\n\n### Why Migrations?\n\nManually altering a database in production is error-prone and leaves no audit trail. Migrations solve this by treating schema changes as code: they are committed to git, reviewed in pull requests, and applied the same way in every environment \u2014 local, staging, and production.\n\n**Benefits:**\n\n- **Reproducibility** \u2014 any developer can recreate the exact database state by running `oo migration:up` from scratch.\n- **History & auditability** \u2014 every schema change is tied to a commit, a date, and an author, making it easy to understand when and why a column or table was added.\n- **Safe deployments** \u2014 CI runs migrations before the application boots, catching schema errors before they reach production.\n- **Rollback capability** \u2014 because changes are incremental and versioned, you can reason about what to undo if a deployment goes wrong.\n- **Team coordination** \u2014 concurrent feature branches each generate their own migration file; the timestamp ordering ensures they are applied in the correct sequence when merged.\n\n**Good practices:**\n\n- One migration per logical change (e.g. add a table, add a column, add an index). Avoid bundling unrelated schema changes in a single file.\n- Never edit a migration that has already been applied in any shared environment \u2014 create a new migration to amend it instead.\n- Always write both `up` and `down` logic so migrations can be rolled back cleanly.\n- Keep migrations idempotent where possible (e.g. `CREATE TABLE IF NOT EXISTS`) to prevent failures on re-runs.\n- Run `oo module:lock` after every new migration to hash the file into the module manifest and enable integrity checks in CI.\n- Test migrations against a real database in CI \u2014 schema errors are invisible to TypeScript's type checker.\n- Avoid putting business logic or data transformations in migrations; keep them strictly structural (DDL) or use a dedicated seed for data.\n\n### Create a Migration\n\nGenerates a timestamped migration file in `modules/<name>/src/migrations/` along with a test file and a `bin/migration/up.ts` runner (if not already present):\n\n```bash\noo migration:create --module user\n```\n\n### Run Migrations\n\nExecutes migrations across all modules sequentially:\n\n```bash\noo migration:up\noo migration:up --drop   # drop database before migrating\n```\n\n---\n\n## Seeds\n\nSeeds populate your database with initial or reference data \u2014 default roles, configuration values, demo content, or test fixtures. Each seed lives in `modules/<name>/src/seeds/` as a YAML file and is executed in order via the seed runner.\n\n### Why Seeds?\n\nHardcoding initial data in migration files mixes structural changes with data concerns, making both harder to maintain. Seeds keep data separate from schema, so they can be re-run independently, updated without touching migrations, and disabled in environments where they are not needed.\n\n**Benefits:**\n\n- **Consistent starting state** \u2014 every developer and every environment boots with the same baseline data, eliminating \"works on my machine\" data discrepancies.\n- **Readable data definitions** \u2014 YAML files are easy to read, diff, and review in pull requests without understanding SQL or TypeScript.\n- **Repeatable setup** \u2014 onboarding a new developer or spinning up a fresh staging environment requires only `oo seed:run` instead of manual database operations.\n- **Separation of concerns** \u2014 schema structure (migrations) and data content (seeds) evolve independently, reducing noise in both histories.\n- **Safe resets** \u2014 `oo seed:run --drop` wipes and repopulates data without touching the schema, useful for resetting demo or test environments.\n\n**Good practices:**\n\n- Use seeds for **reference data** (roles, permissions, countries, currencies) and **development fixtures** (demo users, sample products). Avoid using them for production user data.\n- Keep each seed file focused on a single entity or dataset \u2014 one file per table is a reasonable default.\n- Write seeds so they are idempotent: inserting with `ON CONFLICT DO NOTHING` or checking for existence before inserting prevents errors on re-runs.\n- Never depend on data inserted by another module's seed unless you control the execution order explicitly.\n- Run `oo module:lock` after adding or modifying a seed to update the module manifest and protect file integrity in CI.\n- Mirror your migration order: seed data for a table only after the migration that creates it has been applied.\n- Avoid generating seeds with random or time-dependent values \u2014 deterministic data makes debugging and comparison across environments reliable.\n\n### Create a Seed\n\nGenerates a YAML seed file in `modules/<name>/src/seeds/` along with a test file and a `bin/seed/run.ts` runner (if not already present):\n\n```bash\noo seed:create --module user\noo seed:create --name initial-roles --module user\n```\n\n### Run Seeds\n\nExecutes seeds across all modules sequentially:\n\n```bash\noo seed:run\noo seed:run --drop   # drop data before seeding\n```\n\n---\n\n## Issues\n\nPull Linear issues as local YAML files for offline reference or as input to `/spec:plan`.\n\n### Pull an Issue\n\nFetches a Linear issue by ID and saves it as `issues/<identifier>.yml` (or `modules/<name>/issues/<identifier>.yml` when a module is specified):\n\n```bash\noo issue:pull                               # Prompt for issue ID\noo issue:pull --id OON-123                  # Pull a specific issue by ID\noo issue:pull --id OON-123 --module user    # Save into modules/user/issues/\n```\n\n**Requirements:** `LINEAR_API_KEY` must be set in the environment.\n\n**Good practices:**\n- Pass the saved issue YAML to `/spec:plan` to generate spec files from the issue description.\n- Commit issue files alongside the implementation work so there is a local record of the planned scope.\n- Add `LINEAR_API_KEY` to your local `.env` \u2014 never hardcode it in source.\n\n---\n\n## Generators\n\n### AI\n\nGenerates an AI integration class in `modules/<name>/src/ai/<Name>Ai.ts`. Automatically installs `@ooneex/ai`:\n\n```bash\noo make:ai --name Chat --module user\n```\n\n**Why:** Calling LLM APIs directly from controllers or services mixes infrastructure concerns with business logic and makes it hard to swap providers. A dedicated AI class encapsulates the model, prompt strategy, and configuration in one place.\n\n**Benefits:** Provider-agnostic abstraction, centralised prompt management, easy to mock in tests, swap or upgrade models without touching business logic.\n\n**Good practices:**\n- One class per distinct AI capability (e.g. `ChatAi`, `SummarizeAi`, `ModerationAi`) \u2014 avoid a single god class.\n- Keep system prompts and model configuration inside the class, not scattered across callers.\n- Always handle rate-limit and timeout errors gracefully; never let an AI failure crash the request.\n- Log both the prompt and the response at `debug` level to simplify troubleshooting.\n\n---\n\n### Analytics\n\nGenerates an analytics handler class in `modules/<name>/src/analytics/<Name>Analytics.ts`. Automatically installs `@ooneex/analytics`:\n\n```bash\noo make:analytics --name User --module user\n```\n\n**Why:** Sprinkling raw analytics calls (PostHog, Segment, etc.) throughout controllers couples business logic to a third-party SDK. A dedicated analytics class centralises event definitions and makes it trivial to change or disable the provider.\n\n**Benefits:** Single source of truth for event names and properties, easy to stub in tests, provider can be swapped without touching controllers, events are discoverable by name.\n\n**Good practices:**\n- Name events after business actions, not UI interactions (e.g. `user.subscribed`, not `button.clicked`).\n- Define event property shapes as TypeScript types inside the class.\n- Always fire analytics asynchronously \u2014 never `await` a tracking call on the critical path.\n- Keep one analytics class per domain concept so event ownership is clear.\n\n---\n\n### Cache\n\nGenerates a cache handler class in `modules/<name>/src/cache/<Name>Cache.ts`. Automatically installs `@ooneex/cache`:\n\n```bash\noo make:cache --name User --module user\n```\n\n**Why:** Inline cache calls scattered through services create duplicated TTL values, inconsistent key formats, and make it hard to invalidate related entries. A dedicated cache class owns the key scheme and TTL policy for a given domain object.\n\n**Benefits:** Consistent key naming, single place to update TTLs, easy to add cache warming or invalidation logic, simple to disable caching during tests.\n\n**Good practices:**\n- Prefix keys with the module and entity name to avoid collisions (e.g. `user:profile:{id}`).\n- Define TTLs as named constants, not magic numbers.\n- Always invalidate or update the cache when the underlying data changes \u2014 stale reads are harder to debug than cache misses.\n- Use the cache for reads only; never store the primary copy of data in a cache.\n\n---\n\n### Controller\n\nGenerates an HTTP or WebSocket controller registered in the target module. Prompts for route name, path, and HTTP method if not provided. Automatically installs `@ooneex/controller`:\n\n```bash\noo make:controller --name UserCreate --module user\noo make:controller --name UserCreate --module user --route.name api.user.create --route.path /api/users --route.method POST\noo make:controller --name UserSocket --module user --isSocket\n```\n\n**Why:** Controllers are the entry point for all HTTP and WebSocket interactions. Generating them with a consistent structure ensures route registration, validation, and error handling are set up correctly from the start.\n\n**Benefits:** Automatic route registration in the module, consistent request/response patterns, clear separation between routing and business logic, WebSocket support out of the box.\n\n**Good practices:**\n- One controller per HTTP action (e.g. `UserCreateController`, `UserListController`) \u2014 avoid multi-action controllers.\n- Controllers should be thin: validate input, call a service, return a response. No business logic inside.\n- Prefix route names with the module (e.g. `api.user.create`) to avoid cross-module collisions.\n- Use the generated route name constant everywhere instead of hardcoding URL strings.\n\n---\n\n### Cron\n\nGenerates a cron job class in `modules/<name>/src/crons/<Name>Cron.ts` and registers it in the module. Automatically installs `@ooneex/cron`:\n\n```bash\noo make:cron --name Cleanup --module user\n```\n\n**Why:** Ad-hoc scheduled scripts outside the application are fragile, hard to monitor, and disconnected from the codebase. Cron classes live inside the module that owns the task, are registered with the DI container, and benefit from the same logging and error handling as the rest of the application.\n\n**Benefits:** Centralised schedule management, full access to injected services and repositories, observable via the application logger, easy to disable per environment.\n\n**Good practices:**\n- Name cron classes after the task, not the schedule (e.g. `ExpiredTokenCleanupCron`, not `DailyCron`).\n- Keep the cron class small \u2014 delegate actual work to a service method so the logic is testable independently.\n- Always log the start, end, and outcome of each run.\n- Make cron jobs idempotent: running the same job twice should not corrupt data.\n- Disable background jobs in the `testing` environment to keep tests fast and deterministic.\n\n---\n\n### Database\n\nGenerates a database adapter class in `modules/<name>/src/databases/<Name>Database.ts`. Automatically installs `@ooneex/database`:\n\n```bash\noo make:database --name User --module user\n```\n\n**Why:** Direct use of the ORM or raw query builder in services tightly couples business logic to the database layer. A database adapter wraps the connection and query interface, making it straightforward to configure per-module connections, switch drivers, or mock the database in tests.\n\n**Benefits:** Consistent connection configuration per module, single place to add query logging or instrumentation, easier to test services in isolation by injecting a mock adapter.\n\n**Good practices:**\n- Use the database adapter for raw queries or bulk operations that fall outside the repository pattern.\n- Never expose the raw ORM connection object outside the adapter class.\n- Configure connection pool sizes and timeouts in one place inside the adapter.\n- Prefer the repository pattern for standard CRUD; reach for the database adapter only when you need full query control.\n\n---\n\n### Docker\n\nAdds a Docker service to `modules/app/docker-compose.yml`. Creates the file if it does not exist. Available services: `postgres`, `mysql`, `mongodb`, `redis`, `rabbitmq`, `nats`, `elasticsearch`, `clickhouse`, `minio`, `memcached`, `prometheus`, `grafana`, `jaeger`, `keycloak`, `vault`, `temporal`, `libretranslate`, `maildev`, `ooneex-jade`:\n\n```bash\noo make:docker\noo make:docker --name postgres\noo make:docker --name redis\n```\n\n**Why:** Manually writing Docker Compose service definitions is repetitive, error-prone, and inconsistent across projects. The generator adds a pre-configured, production-ready service block so local infrastructure matches what the application expects.\n\n**Benefits:** Consistent port mappings and environment variables across the team, generated health-check and volume definitions, no need to memorise image names or versions.\n\n**Good practices:**\n- Commit `docker-compose.yml` to source control so every developer uses identical service versions.\n- Use named volumes for persistent data (databases) and anonymous volumes for ephemeral services (caches).\n- Never use Docker Compose in production \u2014 it is a local development tool only.\n- Pin image versions (e.g. `postgres:16`) rather than using `latest` to keep environments stable.\n- Add service dependencies (`depends_on`) so the application container only starts after its databases are healthy.\n\n---\n\n### Entity\n\nGenerates a TypeORM entity class in `modules/<name>/src/entities/<Name>Entity.ts` and registers it in `SharedModule`. Automatically installs `@ooneex/entity`:\n\n```bash\noo make:entity --name User --module user\noo make:entity --name User --module user --tableName users\n```\n\n**Why:** Entities are the single source of truth for your database schema. Generating them with consistent decorators and base class inheritance ensures that timestamps, soft deletes, and other cross-cutting concerns are applied uniformly across every table.\n\n**Benefits:** Automatic registration in `SharedModule`, consistent column conventions (snake_case table names, `created_at`/`updated_at` timestamps), TypeScript types aligned with the database schema.\n\n**Good practices:**\n- Always specify the table name explicitly to avoid surprises from TypeORM's pluralisation logic.\n- Keep entities as pure data structures \u2014 no business logic, no service calls inside entity methods.\n- Add database indexes to columns used in frequent `WHERE` or `ORDER BY` clauses.\n- Use enums for columns with a fixed set of values to enforce data integrity at the database level.\n- Create a migration immediately after adding or modifying an entity so schema and code stay in sync.\n\n---\n\n### Logger\n\nGenerates a logger class in `modules/<name>/src/loggers/<Name>Logger.ts`. Automatically installs `@ooneex/logger`:\n\n```bash\noo make:logger --name Audit --module user\n```\n\n**Why:** Using a global logger everywhere produces undifferentiated log output that is hard to filter by feature or severity. A dedicated logger class per domain adds a consistent context (module name, logger name) to every log entry, making logs actionable in production.\n\n**Benefits:** Structured log entries with automatic context tags, easy to route specific loggers to different backends (file, Better Stack, etc.), no need to repeat context strings across every log call.\n\n**Good practices:**\n- Use the `Audit` logger for security-sensitive actions (login, permission changes) and the default app logger for operational events.\n- Always log at the correct level: `debug` for internal state, `info` for significant business events, `warn` for recoverable problems, `error` for failures that need attention.\n- Include relevant IDs (user ID, request ID) in every log entry to enable correlation across services.\n- Never log sensitive data such as passwords, tokens, or payment details.\n\n---\n\n### Mailer\n\nGenerates a mailer class (`<Name>Mailer.ts`) and its JSX template (`<Name>MailerTemplate.tsx`) in `modules/<name>/src/mailers/`. Automatically installs `@ooneex/mailer`:\n\n```bash\noo make:mailer --name Welcome --module user\n```\n\n**Why:** Composing email HTML inline or with raw string templates is brittle and hard to preview. The generator creates a typed mailer class paired with a JSX template, keeping email logic and presentation cleanly separated and type-safe.\n\n**Benefits:** JSX template enables component reuse and design-system consistency across emails, typed mailer class prevents missing required variables, easy to test rendering without sending real emails.\n\n**Good practices:**\n- One mailer per transactional email type (e.g. `WelcomeMailer`, `PasswordResetMailer`).\n- Never send emails synchronously on the request path \u2014 enqueue them via a job or pub/sub event.\n- Always provide a plain-text fallback alongside the HTML template for clients that block images.\n- Test email rendering in multiple clients (Gmail, Outlook, Apple Mail) before deploying \u2014 CSS support varies widely.\n- Use the `testing` environment mailer backend to capture sent emails without delivering them.\n\n---\n\n### Middleware\n\nGenerates an HTTP or WebSocket middleware class registered in the target module. Automatically installs `@ooneex/middleware`:\n\n```bash\noo make:middleware --name Auth --module user\noo make:middleware --name Auth --module user --isSocket\n```\n\n**Why:** Cross-cutting concerns like authentication, CORS, request logging, and input sanitisation should not live inside controllers. Middleware classes intercept requests before they reach a controller, keeping that logic reusable and independently testable.\n\n**Benefits:** Reusable across multiple controllers within the module, auto-registered in the middleware pipeline, full access to injected services via DI, works identically for HTTP and WebSocket routes.\n\n**Good practices:**\n- Keep middleware single-purpose (e.g. `AuthMiddleware` only handles authentication, not rate limiting).\n- Always call `next()` explicitly or return a response \u2014 never leave the pipeline hanging.\n- Order matters: authentication middleware must run before authorisation middleware.\n- Avoid heavy computation in middleware; defer expensive work to the service layer.\n- Write unit tests that verify the middleware passes, blocks, and modifies requests as expected.\n\n---\n\n### Permission\n\nGenerates a permission class in `modules/<name>/src/permissions/<Name>Permission.ts`. Automatically installs `@ooneex/permission`:\n\n```bash\noo make:permission --name User --module user\n```\n\n**Why:** Scattering permission checks across controllers and services leads to inconsistency and makes auditing access control difficult. A dedicated permission class per domain centralises all access rules for that domain in one reviewable place.\n\n**Benefits:** All permissions for a domain are discoverable in a single file, easy to audit who can do what, permissions can be reused across multiple controllers without duplication, changes to access rules require touching only one class.\n\n**Good practices:**\n- Name permissions after the action and resource (e.g. `UserPermission` checks `canCreate`, `canUpdate`, `canDelete`).\n- Always check permissions in middleware or the service layer \u2014 never in the entity or repository.\n- Combine with roles (RBAC) for coarse-grained access and permissions for fine-grained control.\n- Write tests that assert both allowed and denied cases for every permission rule.\n- Never hardcode user IDs or emails inside permission logic; use roles and attributes instead.\n\n---\n\n### PubSub\n\nGenerates a pub/sub event class in `modules/<name>/src/events/<Name>Event.ts` and registers it in the module. Automatically installs `@ooneex/pub-sub`:\n\n```bash\noo make:pubsub --name UserCreated --module user\noo make:pubsub --name UserCreated --module user --channel user-created\n```\n\n**Why:** Direct calls between modules create tight coupling that makes the codebase fragile and hard to extend. Pub/sub events decouple the publisher from the subscriber: the `user` module emits `UserCreated` without knowing or caring which other modules react to it.\n\n**Benefits:** Loose coupling between modules, multiple subscribers can react to the same event independently, easy to add new reactions without modifying the publisher, events are named and typed so their contracts are explicit.\n\n**Good practices:**\n- Name events in the past tense (e.g. `UserCreated`, `OrderShipped`) to make clear they describe something that already happened.\n- Keep event payloads small and serialisable \u2014 include IDs rather than full entity objects where possible.\n- Subscribe in the module that owns the reaction, not in the module that owns the event.\n- Make event handlers idempotent: the same event may be delivered more than once in failure scenarios.\n- Log every event published and consumed to simplify debugging distributed flows.\n\n---\n\n### Repository\n\nGenerates a repository class for data access in `modules/<name>/src/repositories/<Name>Repository.ts`. Automatically installs `@ooneex/repository`:\n\n```bash\noo make:repository --name User --module user\n```\n\n**Why:** Putting database queries directly in services mixes business logic with persistence concerns and makes services impossible to test without a database. The repository pattern isolates all data-access code behind a typed interface that can be mocked in tests.\n\n**Benefits:** Services remain database-agnostic, all queries for an entity are discoverable in one class, easy to swap the underlying ORM or database without touching business logic, clean boundary for unit testing.\n\n**Good practices:**\n- One repository per entity (e.g. `UserRepository` owns all queries against the `users` table).\n- Repositories should only contain query logic \u2014 no business rules, no validation, no event publishing.\n- Use descriptive method names that reflect intent (e.g. `findActiveByEmail`, `findExpiredTokens`) rather than generic `find` with complex filter objects.\n- Return domain objects or plain data \u2014 never expose raw ORM query builders to callers.\n- Add pagination to any method that can return an unbounded number of rows.\n\n---\n\n### Service\n\nGenerates a service class in `modules/<name>/src/services/<Name>Service.ts`. Automatically installs `@ooneex/service`:\n\n```bash\noo make:service --name User --module user\n```\n\n**Why:** Business logic scattered across controllers is impossible to test, reuse, or reason about. Services are the home of all business rules, orchestrating repositories, events, and other services in a single, testable unit.\n\n**Benefits:** Business logic is testable without HTTP, reusable across multiple controllers or cron jobs, dependencies are explicit via constructor injection, easy to mock at the service boundary in integration tests.\n\n**Good practices:**\n- One service per aggregate or major business capability (e.g. `UserService` for user lifecycle, `BillingService` for payment flows).\n- Services should call repositories for data, never query the database directly.\n- Keep services stateless \u2014 all required data should come from method arguments or injected dependencies.\n- Raise typed exceptions (e.g. `UserNotFoundException`) rather than returning `null` or error codes.\n- A service method should do one thing; if a method grows beyond ~20 lines, consider extracting a helper or sub-service.\n\n---\n\n### Storage\n\nGenerates a file storage class in `modules/<name>/src/storage/<Name>Storage.ts`. Automatically installs `@ooneex/storage`:\n\n```bash\noo make:storage --name Avatar --module user\n```\n\n**Why:** Coupling file upload logic directly to a specific provider (S3, Cloudflare R2, local filesystem) makes it painful to change backends and duplicates configuration across the codebase. A storage class abstracts the provider behind a consistent interface scoped to a specific asset type.\n\n**Benefits:** Provider-agnostic uploads and reads, all storage configuration for an asset type in one class, easy to switch between local filesystem (development) and cloud storage (production) via environment variables, consistent file-naming and path conventions.\n\n**Good practices:**\n- Name storage classes after the asset they manage (e.g. `AvatarStorage`, `InvoiceStorage`).\n- Always validate file type and size before passing to the storage class \u2014 never trust client-supplied content types.\n- Generate deterministic, collision-resistant file names (e.g. `{userId}/{uuid}.{ext}`) rather than using the original filename.\n- Never store the full URL in the database \u2014 store only the path or key and derive the URL at read time so it works across environments.\n- Delete orphaned files when the associated entity is deleted to avoid unbounded storage growth.\n\n---\n\n### Vector Database\n\nGenerates a vector database class in `modules/<name>/src/databases/<Name>VectorDatabase.ts`. Automatically installs `@ooneex/rag`:\n\n```bash\noo make:vector-database --name Knowledge --module user\n```\n\n**Why:** Semantic search and Retrieval-Augmented Generation (RAG) require storing and querying high-dimensional embeddings, which relational databases are not designed for. A dedicated vector database class encapsulates the embedding model, index configuration, and similarity-search logic in one place.\n\n**Benefits:** Centralised embedding and retrieval strategy per knowledge domain, easy to swap vector backends (pgvector, Qdrant, etc.), consistent chunking and metadata conventions, decoupled from the LLM layer so both can evolve independently.\n\n**Good practices:**\n- One vector database class per knowledge domain (e.g. `KnowledgeVectorDatabase`, `ProductCatalogVectorDatabase`).\n- Always store the source document ID alongside each embedding so retrieved chunks can be traced back to their origin.\n- Use a consistent chunking strategy (fixed-size or sentence-boundary) within a class \u2014 mixing strategies pollutes the index.\n- Re-index when the embedding model changes; embeddings from different models are not comparable.\n- Cache frequently retrieved embeddings to avoid redundant model calls on hot queries.\n\n---\n\n## Claude\n\nThis project ships with a set of **Claude Code skills** \u2014 pre-built instruction sets that tell Claude exactly how to scaffold, implement, and test each type of artefact in this codebase. Skills eliminate the gap between \"generate the files\" and \"ship working code\": each skill runs the CLI generator, reads the output, completes the implementation, writes tests, and lints \u2014 all in one `/command`.\n\n### Why Skills?\n\nRunning `oo make:service` creates a skeleton. A Claude skill does that *and* completes the business logic, writes a meaningful test suite, applies coding conventions, and formats the result \u2014 turning a 10-step workflow into a single prompt.\n\n**Benefits:**\n- Consistent code quality across every artefact, regardless of who wrote it\n- Conventions (visibility modifiers, naming suffixes, DI patterns) are enforced automatically\n- Tests are generated alongside implementation, not as an afterthought\n- Skills chain together \u2014 `make:controller` automatically triggers `make:service` and `make:pubsub`\n\n### How to Use\n\nOpen Claude Code in the project root and type `/skill-name`. Claude will execute the full workflow described in the skill. You can pass arguments inline:\n\n```\n/make:service --name=UserCreate --module=user\n/make:controller --name=UserCreate --module=user --route.path=/users --route.method=POST\n/commit\n```\n\nIf you omit arguments, Claude will prompt you for the required values.\n\n> **Important:** Always run skills from the project root, not from inside a module directory.\n\n### Available Skills\n\n#### Code Quality\n\n| Skill | Description |\n|---|---|\n| `/optimize` | Enforce naming conventions, remove duplication, improve performance, and restructure tests across a module |\n| `/commit` | Analyze staged changes, group them by module, and create properly scoped conventional commits |\n\n#### Generators\n\n| Skill | Description |\n|---|---|\n| `/make:ai` | Generate an AI integration class with `run` and `runStream` methods, wired to `@ooneex/ai` |\n| `/make:analytics` | Generate an analytics handler class for tracking domain events via `@ooneex/analytics` |\n| `/make:cache` | Generate a cache handler class with key and TTL management via `@ooneex/cache` |\n| `/make:command` | Generate a CLI command class implementing `ICommand` via `@ooneex/cli` |\n| `/make:controller` | Generate an HTTP or WebSocket controller with route type, validation, roles, service, and pub/sub event |\n| `/make:cron` | Generate a cron job class registered in its module via `@ooneex/cron` |\n| `/make:database` | Generate a database adapter class for raw queries via `@ooneex/database` |\n| `/make:entity` | Generate a TypeORM entity class registered in `SharedModule` via `@ooneex/entity` |\n| `/make:logger` | Generate a structured logger class with domain context via `@ooneex/logger` |\n| `/make:mailer` | Generate a mailer class and its JSX email template via `@ooneex/mailer` |\n| `/make:middleware` | Generate an HTTP or WebSocket middleware class registered in the module via `@ooneex/middleware` |\n| `/make:permission` | Generate a permission class centralising access rules for a domain via `@ooneex/permission` |\n| `/make:pubsub` | Generate a pub/sub event class registered in the module via `@ooneex/pub-sub` |\n| `/make:repository` | Generate a repository class for typed data access via `@ooneex/repository` |\n| `/make:service` | Generate a service class implementing `IService` with business logic and tests |\n| `/make:storage` | Generate a file storage class for asset management via `@ooneex/storage` |\n| `/make:vector-database` | Generate a vector database class for semantic search and RAG via `@ooneex/rag` |\n\n#### Database\n\n| Skill | Description |\n|---|---|\n| `/migration:create` | Generate a migration file with `up`/`down` methods, index guidance, and structural tests |\n| `/seed:create` | Generate a seed class and its YAML data file with idempotent insertion logic |\n\n#### Spec\n\n| Skill | Description |\n|---|---|\n| `/spec:plan` | Parse user-provided content and produce one `specs/<spec-name>.spec.yml` file per entity/action pair |\n| `/spec:implement` | Read a single spec YML entry and implement entity, repository, service, controller/command, and optional resources |\n\n### Coding Conventions Enforced by Skills\n\nAll generator skills automatically apply the conventions defined in `/optimize`:\n\n- **Visibility modifiers** \u2014 every class method and property has explicit `public`, `private`, or `protected`\n- **Naming suffixes** \u2014 types end with `Type`, interfaces start with `I`\n- **Arrow functions** \u2014 used everywhere except class methods\n- **No non-null assertions** \u2014 use default values or optional types instead\n- **Dependency injection** \u2014 constructor injection via `@inject()` from `@ooneex/container`\n- **Code hygiene** \u2014 no unused imports, no dead code, no bare `TODO` comments\n\n---\n\n## Release\n\n```bash\noo make:release\n```\n\nScans every `packages/` and `modules/` directory for unreleased conventional commits and, for each one that has them, performs a full release cycle automatically:\n\n1. **Detects unreleased work** \u2014 finds the last git tag matching `<package-name>@*` and lists all conventional commits that have landed since then in that directory. Packages with no new commits are skipped.\n2. **Bumps the version** in `package.json`:\n   - `minor` (e.g. `1.2.0 \u2192 1.3.0`) when any commit is of type `feat`\n   - `patch` (e.g. `1.2.0 \u2192 1.2.1`) for all other types (`fix`, `refactor`, `perf`, `docs`, `chore`, \u2026)\n3. **Updates `CHANGELOG.md`** with a dated version section. Commits are grouped into standard Keep-a-Changelog categories and linked to their SHA on the remote:\n\n   | Commit type | Changelog category |\n   |---|---|\n   | `feat` | Added |\n   | `fix` | Fixed |\n   | `refactor`, `perf`, `style`, `docs`, `build`, `ci`, `chore` | Changed |\n   | `revert` | Removed |\n\n4. **Creates a release commit** \u2014 stages `package.json` and `CHANGELOG.md` then commits with the message `chore(release): <name>@<version>`.\n5. **Creates an annotated git tag** \u2014 `<name>@<version>` (e.g. `@acme/user@1.3.0`).\n6. **Prompts to push** \u2014 after all packages are processed, asks whether to push commits and tags to the remote. If confirmed, it also runs `bun install`, commits the updated `bun.lock`, and pushes everything.\n\n> **Note:** This command requires conventional commits (`type(scope): Subject`). Non-conventional commits are silently ignored when building the changelog.\n\n---\n\n## Scripts\n\n| Command | Description |\n|---|---|\n| `bun run fmt` | Format all source files with Biome |\n| `bun run lint` | Lint all modules with Biome and TypeScript |\n| `bun run test` | Run tests across all modules |\n| `bun run commit` | Interactive conventional commit prompt |\n";
+var README_md_default = "# {{NAME}}\n\nA modular, enterprise-grade backend framework built with TypeScript and Bun, powered by the **@ooneex** ecosystem.\n\n## Prerequisites\n\n- [Bun](https://bun.sh) (latest)\n- [Docker](https://www.docker.com/) & Docker Compose\n\n## Getting Started\n\n### Install Dependencies\n\n```bash\nbun install\n```\n\n### Environment Configuration\n\nCopy the environment template and fill in the required values:\n\n```bash\ncp modules/app/.env.example modules/app/.env\n```\n\n| Variable | Description | Required |\n|---|---|---|\n| `APP_ENV` | Application environment (`local`, `development`, `staging`, `testing`, `production`, \u2026) | Yes |\n| `PORT` | Server port number (default: `3000`) | Yes |\n| `HOST_NAME` | Server hostname (default: `0.0.0.0`) | Yes |\n| `CSRF_SECRET` | Secret key for CSRF token generation and verification | Yes |\n| `LOGS_DATABASE_URL` | Database URL for storing application logs | No |\n| `BETTERSTACK_LOGGER_SOURCE_TOKEN` | Logtail source token for Better Stack logging | No |\n| `BETTERSTACK_EXCEPTION_LOGGER_APPLICATION_TOKEN` | Better Stack token for exception tracking | No |\n| `ANALYTICS_POSTHOG_PROJECT_TOKEN` | PostHog API key for event tracking | No |\n| `CACHE_REDIS_URL` | Redis connection URL for caching | No |\n| `CACHE_UPSTASH_REDIS_REST_URL` | Upstash Redis REST URL for serverless caching | No |\n| `PUBSUB_REDIS_URL` | Redis connection URL for pub/sub messaging | No |\n| `RATE_LIMIT_REDIS_URL` | Redis connection URL for rate limiting | No |\n| `CORS_ORIGINS` | Comma-separated allowed origins or `*` (default: `*`) | No |\n| `CORS_METHODS` | Comma-separated HTTP methods | No |\n| `CORS_HEADERS` | Comma-separated allowed request headers | No |\n| `CORS_CREDENTIALS` | Allow credentials: `true` or `false` | No |\n| `DATABASE_URL` | PostgreSQL connection URL | No |\n| `DATABASE_REDIS_URL` | Redis connection URL for Redis-based database operations | No |\n| `SQLITE_DATABASE_PATH` | SQLite database file path | No |\n| `STORAGE_CLOUDFLARE_ACCESS_KEY` | Cloudflare R2 access key ID | No |\n| `STORAGE_CLOUDFLARE_SECRET_KEY` | Cloudflare R2 secret access key | No |\n| `STORAGE_CLOUDFLARE_ENDPOINT` | Cloudflare R2 endpoint URL | No |\n| `STORAGE_BUNNY_ACCESS_KEY` | BunnyCDN access key | No |\n| `STORAGE_BUNNY_STORAGE_ZONE` | BunnyCDN storage zone name | No |\n| `FILESYSTEM_STORAGE_PATH` | Base directory path for local file storage | No |\n| `MAILER_SENDER_NAME` | Display name for email sender | No |\n| `MAILER_SENDER_ADDRESS` | Email address for sender | No |\n| `RESEND_API_KEY` | Resend email service API key | No |\n| `JWT_SECRET` | Secret key for HS256 JWT signing and verification | No |\n| `OPENROUTER_API_KEY` | OpenRouter API key for accessing 300+ AI models | No |\n| `OPENAI_API_KEY` | OpenAI API key | No |\n| `ANTHROPIC_API_KEY` | Anthropic API key for Claude models | No |\n| `GEMINI_API_KEY` | Google Gemini API key | No |\n| `GROQ_API_KEY` | Groq API key for LLM inference | No |\n| `POLAR_ACCESS_TOKEN` | Polar payment platform access token | No |\n| `CLERK_SECRET_KEY` | Clerk authentication secret key | No |\n\n### Start the App\n\nStarts Docker services (if a `docker-compose.yml` is present) and launches the application with hot reload:\n\n```bash\noo app:start\n```\n\n### Stop the App\n\nStops all Docker services:\n\n```bash\noo app:stop\n```\n\n### Build the App\n\nCompiles the application for production. Output is written to the `dist` directory:\n\n```bash\noo app:build\n```\n\n---\n\n## Modules\n\nModules are the core organizational unit. Each module lives under `modules/<name>/` and contains its own controllers, services, repositories, entities, migrations, and seeds.\n\n### Why Modules?\n\nA flat codebase quickly becomes hard to navigate and reason about as an application grows. Modules address this by enforcing **vertical slicing**: all code related to a single business domain (e.g. `user`, `order`, `billing`) lives together rather than being scattered across generic `controllers/`, `services/`, and `repositories/` folders.\n\n**Benefits:**\n\n- **Domain isolation** \u2014 changes to one feature cannot accidentally break another; each module is a self-contained unit with explicit boundaries.\n- **Parallel development** \u2014 teams can work on separate modules without stepping on each other's code or creating merge conflicts in shared directories.\n- **Independent deployment** \u2014 a module can be extracted into a standalone service later with minimal refactoring because its code is already co-located.\n- **Simpler onboarding** \u2014 a new developer understands the scope of a feature by exploring a single directory instead of tracing imports across the whole project.\n- **Scoped migrations & seeds** \u2014 database changes stay close to the entities they affect, making rollbacks and reviews straightforward.\n\n**Good practices:**\n\n- Name modules after business domains (`user`, `product`, `payment`), not technical layers (`controllers`, `helpers`).\n- Keep modules small and focused. If a module grows beyond ~10 controllers or services, consider splitting it by sub-domain.\n- Never import from another module's internal files directly \u2014 expose only what is needed through the module's public index.\n- Register all entities in `SharedModule` (done automatically by `oo make:entity`) so the ORM has a single source of truth.\n- Run `oo module:lock` after every migration or seed change to protect file integrity in CI.\n- Prefix route names with the module name (e.g. `api.user.create`) to avoid collisions across modules.\n\n### Create a Module\n\nScaffolds a new module with all required structure, registers it in `AppModule`, adds its entities to `SharedModule`, and updates `tsconfig.json` path aliases and commitlint config:\n\n```bash\noo module:create\noo module:create --name user\n```\n\n### Lock a Module\n\nHashes migration and seed files into a module manifest (`.yml`) for integrity verification. Run this after adding or modifying migrations/seeds:\n\n```bash\noo module:lock --module user\noo module:lock --module user --override   # force update existing hashes\n```\n\n### Delete a Module\n\nRemoves a module and cleans up all references from `AppModule`, `SharedModule`, `tsconfig.json`, and commitlint config. The `app` and `shared` core modules cannot be removed:\n\n```bash\noo module:remove\noo module:remove --name user\noo module:remove --name user --silent    # skip confirmation prompt\n```\n\n---\n\n## Migrations\n\nMigrations are versioned, incremental SQL scripts that evolve your database schema over time. Each migration lives in `modules/<name>/src/migrations/` and is executed in order, making every schema change reproducible, reviewable, and reversible.\n\n### Why Migrations?\n\nManually altering a database in production is error-prone and leaves no audit trail. Migrations solve this by treating schema changes as code: they are committed to git, reviewed in pull requests, and applied the same way in every environment \u2014 local, staging, and production.\n\n**Benefits:**\n\n- **Reproducibility** \u2014 any developer can recreate the exact database state by running `oo migration:up` from scratch.\n- **History & auditability** \u2014 every schema change is tied to a commit, a date, and an author, making it easy to understand when and why a column or table was added.\n- **Safe deployments** \u2014 CI runs migrations before the application boots, catching schema errors before they reach production.\n- **Rollback capability** \u2014 because changes are incremental and versioned, you can reason about what to undo if a deployment goes wrong.\n- **Team coordination** \u2014 concurrent feature branches each generate their own migration file; the timestamp ordering ensures they are applied in the correct sequence when merged.\n\n**Good practices:**\n\n- One migration per logical change (e.g. add a table, add a column, add an index). Avoid bundling unrelated schema changes in a single file.\n- Never edit a migration that has already been applied in any shared environment \u2014 create a new migration to amend it instead.\n- Always write both `up` and `down` logic so migrations can be rolled back cleanly.\n- Keep migrations idempotent where possible (e.g. `CREATE TABLE IF NOT EXISTS`) to prevent failures on re-runs.\n- Run `oo module:lock` after every new migration to hash the file into the module manifest and enable integrity checks in CI.\n- Test migrations against a real database in CI \u2014 schema errors are invisible to TypeScript's type checker.\n- Avoid putting business logic or data transformations in migrations; keep them strictly structural (DDL) or use a dedicated seed for data.\n\n### Create a Migration\n\nGenerates a timestamped migration file in `modules/<name>/src/migrations/` along with a test file and a `bin/migration/up.ts` runner (if not already present):\n\n```bash\noo migration:create --module user\n```\n\n### Run Migrations\n\nExecutes migrations across all modules sequentially:\n\n```bash\noo migration:up\noo migration:up --drop   # drop database before migrating\n```\n\n---\n\n## Seeds\n\nSeeds populate your database with initial or reference data \u2014 default roles, configuration values, demo content, or test fixtures. Each seed lives in `modules/<name>/src/seeds/` as a YAML file and is executed in order via the seed runner.\n\n### Why Seeds?\n\nHardcoding initial data in migration files mixes structural changes with data concerns, making both harder to maintain. Seeds keep data separate from schema, so they can be re-run independently, updated without touching migrations, and disabled in environments where they are not needed.\n\n**Benefits:**\n\n- **Consistent starting state** \u2014 every developer and every environment boots with the same baseline data, eliminating \"works on my machine\" data discrepancies.\n- **Readable data definitions** \u2014 YAML files are easy to read, diff, and review in pull requests without understanding SQL or TypeScript.\n- **Repeatable setup** \u2014 onboarding a new developer or spinning up a fresh staging environment requires only `oo seed:run` instead of manual database operations.\n- **Separation of concerns** \u2014 schema structure (migrations) and data content (seeds) evolve independently, reducing noise in both histories.\n- **Safe resets** \u2014 `oo seed:run --drop` wipes and repopulates data without touching the schema, useful for resetting demo or test environments.\n\n**Good practices:**\n\n- Use seeds for **reference data** (roles, permissions, countries, currencies) and **development fixtures** (demo users, sample products). Avoid using them for production user data.\n- Keep each seed file focused on a single entity or dataset \u2014 one file per table is a reasonable default.\n- Write seeds so they are idempotent: inserting with `ON CONFLICT DO NOTHING` or checking for existence before inserting prevents errors on re-runs.\n- Never depend on data inserted by another module's seed unless you control the execution order explicitly.\n- Run `oo module:lock` after adding or modifying a seed to update the module manifest and protect file integrity in CI.\n- Mirror your migration order: seed data for a table only after the migration that creates it has been applied.\n- Avoid generating seeds with random or time-dependent values \u2014 deterministic data makes debugging and comparison across environments reliable.\n\n### Create a Seed\n\nGenerates a YAML seed file in `modules/<name>/src/seeds/` along with a test file and a `bin/seed/run.ts` runner (if not already present):\n\n```bash\noo seed:create --module user\noo seed:create --name initial-roles --module user\n```\n\n### Run Seeds\n\nExecutes seeds across all modules sequentially:\n\n```bash\noo seed:run\noo seed:run --drop   # drop data before seeding\n```\n\n---\n\n## Issues\n\nPull Linear issues as local YAML files for offline reference or as input to `/spec:plan`.\n\n### Pull an Issue\n\nFetches a Linear issue by ID and saves it as `issues/<identifier>.yml` (or `modules/<name>/issues/<identifier>.yml` when a module is specified):\n\n```bash\noo issue:pull                               # Prompt for issue ID\noo issue:pull --id OON-123                  # Pull a specific issue by ID\noo issue:pull --id OON-123 --module user    # Save into modules/user/issues/\n```\n\n**Requirements:** `LINEAR_API_KEY` must be set in the environment.\n\n**Good practices:**\n- Pass the saved issue YAML to `/spec:plan` to generate spec files from the issue description.\n- Commit issue files alongside the implementation work so there is a local record of the planned scope.\n- Add `LINEAR_API_KEY` to your local `.env` \u2014 never hardcode it in source.\n\n---\n\n## Generators\n\n### AI\n\nGenerates an AI integration class in `modules/<name>/src/ai/<Name>Ai.ts`. Automatically installs `@ooneex/ai`:\n\n```bash\noo make:ai --name Chat --module user\n```\n\n**Why:** Calling LLM APIs directly from controllers or services mixes infrastructure concerns with business logic and makes it hard to swap providers. A dedicated AI class encapsulates the model, prompt strategy, and configuration in one place.\n\n**Benefits:** Provider-agnostic abstraction, centralised prompt management, easy to mock in tests, swap or upgrade models without touching business logic.\n\n**Good practices:**\n- One class per distinct AI capability (e.g. `ChatAi`, `SummarizeAi`, `ModerationAi`) \u2014 avoid a single god class.\n- Keep system prompts and model configuration inside the class, not scattered across callers.\n- Always handle rate-limit and timeout errors gracefully; never let an AI failure crash the request.\n- Log both the prompt and the response at `debug` level to simplify troubleshooting.\n\n---\n\n### Analytics\n\nGenerates an analytics handler class in `modules/<name>/src/analytics/<Name>Analytics.ts`. Automatically installs `@ooneex/analytics`:\n\n```bash\noo make:analytics --name User --module user\n```\n\n**Why:** Sprinkling raw analytics calls (PostHog, Segment, etc.) throughout controllers couples business logic to a third-party SDK. A dedicated analytics class centralises event definitions and makes it trivial to change or disable the provider.\n\n**Benefits:** Single source of truth for event names and properties, easy to stub in tests, provider can be swapped without touching controllers, events are discoverable by name.\n\n**Good practices:**\n- Name events after business actions, not UI interactions (e.g. `user.subscribed`, not `button.clicked`).\n- Define event property shapes as TypeScript types inside the class.\n- Always fire analytics asynchronously \u2014 never `await` a tracking call on the critical path.\n- Keep one analytics class per domain concept so event ownership is clear.\n\n---\n\n### Cache\n\nGenerates a cache handler class in `modules/<name>/src/cache/<Name>Cache.ts`. Automatically installs `@ooneex/cache`:\n\n```bash\noo make:cache --name User --module user\n```\n\n**Why:** Inline cache calls scattered through services create duplicated TTL values, inconsistent key formats, and make it hard to invalidate related entries. A dedicated cache class owns the key scheme and TTL policy for a given domain object.\n\n**Benefits:** Consistent key naming, single place to update TTLs, easy to add cache warming or invalidation logic, simple to disable caching during tests.\n\n**Good practices:**\n- Prefix keys with the module and entity name to avoid collisions (e.g. `user:profile:{id}`).\n- Define TTLs as named constants, not magic numbers.\n- Always invalidate or update the cache when the underlying data changes \u2014 stale reads are harder to debug than cache misses.\n- Use the cache for reads only; never store the primary copy of data in a cache.\n\n---\n\n### Controller\n\nGenerates an HTTP or WebSocket controller registered in the target module. Prompts for route name, path, and HTTP method if not provided. Automatically installs `@ooneex/controller`:\n\n```bash\noo make:controller --name UserCreate --module user\noo make:controller --name UserCreate --module user --route.name api.user.create --route.path /api/users --route.method POST\noo make:controller --name UserSocket --module user --isSocket\n```\n\n**Why:** Controllers are the entry point for all HTTP and WebSocket interactions. Generating them with a consistent structure ensures route registration, validation, and error handling are set up correctly from the start.\n\n**Benefits:** Automatic route registration in the module, consistent request/response patterns, clear separation between routing and business logic, WebSocket support out of the box.\n\n**Good practices:**\n- One controller per HTTP action (e.g. `UserCreateController`, `UserListController`) \u2014 avoid multi-action controllers.\n- Controllers should be thin: validate input, call a service, return a response. No business logic inside.\n- Prefix route names with the module (e.g. `api.user.create`) to avoid cross-module collisions.\n- Use the generated route name constant everywhere instead of hardcoding URL strings.\n\n---\n\n### Cron\n\nGenerates a cron job class in `modules/<name>/src/crons/<Name>Cron.ts` and registers it in the module. Automatically installs `@ooneex/cron`:\n\n```bash\noo make:cron --name Cleanup --module user\n```\n\n**Why:** Ad-hoc scheduled scripts outside the application are fragile, hard to monitor, and disconnected from the codebase. Cron classes live inside the module that owns the task, are registered with the DI container, and benefit from the same logging and error handling as the rest of the application.\n\n**Benefits:** Centralised schedule management, full access to injected services and repositories, observable via the application logger, easy to disable per environment.\n\n**Good practices:**\n- Name cron classes after the task, not the schedule (e.g. `ExpiredTokenCleanupCron`, not `DailyCron`).\n- Keep the cron class small \u2014 delegate actual work to a service method so the logic is testable independently.\n- Always log the start, end, and outcome of each run.\n- Make cron jobs idempotent: running the same job twice should not corrupt data.\n- Disable background jobs in the `testing` environment to keep tests fast and deterministic.\n\n---\n\n### Database\n\nGenerates a database adapter class in `modules/<name>/src/databases/<Name>Database.ts`. Automatically installs `@ooneex/database`:\n\n```bash\noo make:database --name User --module user\n```\n\n**Why:** Direct use of the ORM or raw query builder in services tightly couples business logic to the database layer. A database adapter wraps the connection and query interface, making it straightforward to configure per-module connections, switch drivers, or mock the database in tests.\n\n**Benefits:** Consistent connection configuration per module, single place to add query logging or instrumentation, easier to test services in isolation by injecting a mock adapter.\n\n**Good practices:**\n- Use the database adapter for raw queries or bulk operations that fall outside the repository pattern.\n- Never expose the raw ORM connection object outside the adapter class.\n- Configure connection pool sizes and timeouts in one place inside the adapter.\n- Prefer the repository pattern for standard CRUD; reach for the database adapter only when you need full query control.\n\n---\n\n### Docker\n\nAdds a Docker service to `modules/app/docker-compose.yml`. Creates the file if it does not exist. Available services: `postgres`, `mysql`, `mongodb`, `redis`, `rabbitmq`, `nats`, `elasticsearch`, `clickhouse`, `minio`, `memcached`, `prometheus`, `grafana`, `jaeger`, `keycloak`, `vault`, `temporal`, `libretranslate`, `maildev`, `ooneex-jade`:\n\n```bash\noo make:docker\noo make:docker --name postgres\noo make:docker --name redis\n```\n\n**Why:** Manually writing Docker Compose service definitions is repetitive, error-prone, and inconsistent across projects. The generator adds a pre-configured, production-ready service block so local infrastructure matches what the application expects.\n\n**Benefits:** Consistent port mappings and environment variables across the team, generated health-check and volume definitions, no need to memorise image names or versions.\n\n**Good practices:**\n- Commit `docker-compose.yml` to source control so every developer uses identical service versions.\n- Use named volumes for persistent data (databases) and anonymous volumes for ephemeral services (caches).\n- Never use Docker Compose in production \u2014 it is a local development tool only.\n- Pin image versions (e.g. `postgres:16`) rather than using `latest` to keep environments stable.\n- Add service dependencies (`depends_on`) so the application container only starts after its databases are healthy.\n\n---\n\n### Entity\n\nGenerates a TypeORM entity class in `modules/<name>/src/entities/<Name>Entity.ts` and registers it in `SharedModule`. Automatically installs `@ooneex/entity`:\n\n```bash\noo make:entity --name User --module user\noo make:entity --name User --module user --tableName users\n```\n\n**Why:** Entities are the single source of truth for your database schema. Generating them with consistent decorators and base class inheritance ensures that timestamps, soft deletes, and other cross-cutting concerns are applied uniformly across every table.\n\n**Benefits:** Automatic registration in `SharedModule`, consistent column conventions (snake_case table names, `created_at`/`updated_at` timestamps), TypeScript types aligned with the database schema.\n\n**Good practices:**\n- Always specify the table name explicitly to avoid surprises from TypeORM's pluralisation logic.\n- Keep entities as pure data structures \u2014 no business logic, no service calls inside entity methods.\n- Add database indexes to columns used in frequent `WHERE` or `ORDER BY` clauses.\n- Use enums for columns with a fixed set of values to enforce data integrity at the database level.\n- Create a migration immediately after adding or modifying an entity so schema and code stay in sync.\n\n---\n\n### Logger\n\nGenerates a logger class in `modules/<name>/src/loggers/<Name>Logger.ts`. Automatically installs `@ooneex/logger`:\n\n```bash\noo make:logger --name Audit --module user\n```\n\n**Why:** Using a global logger everywhere produces undifferentiated log output that is hard to filter by feature or severity. A dedicated logger class per domain adds a consistent context (module name, logger name) to every log entry, making logs actionable in production.\n\n**Benefits:** Structured log entries with automatic context tags, easy to route specific loggers to different backends (file, Better Stack, etc.), no need to repeat context strings across every log call.\n\n**Good practices:**\n- Use the `Audit` logger for security-sensitive actions (login, permission changes) and the default app logger for operational events.\n- Always log at the correct level: `debug` for internal state, `info` for significant business events, `warn` for recoverable problems, `error` for failures that need attention.\n- Include relevant IDs (user ID, request ID) in every log entry to enable correlation across services.\n- Never log sensitive data such as passwords, tokens, or payment details.\n\n---\n\n### Mailer\n\nGenerates a mailer class (`<Name>Mailer.ts`) and its JSX template (`<Name>MailerTemplate.tsx`) in `modules/<name>/src/mailers/`. Automatically installs `@ooneex/mailer`:\n\n```bash\noo make:mailer --name Welcome --module user\n```\n\n**Why:** Composing email HTML inline or with raw string templates is brittle and hard to preview. The generator creates a typed mailer class paired with a JSX template, keeping email logic and presentation cleanly separated and type-safe.\n\n**Benefits:** JSX template enables component reuse and design-system consistency across emails, typed mailer class prevents missing required variables, easy to test rendering without sending real emails.\n\n**Good practices:**\n- One mailer per transactional email type (e.g. `WelcomeMailer`, `PasswordResetMailer`).\n- Never send emails synchronously on the request path \u2014 enqueue them via a job or pub/sub event.\n- Always provide a plain-text fallback alongside the HTML template for clients that block images.\n- Test email rendering in multiple clients (Gmail, Outlook, Apple Mail) before deploying \u2014 CSS support varies widely.\n- Use the `testing` environment mailer backend to capture sent emails without delivering them.\n\n---\n\n### Middleware\n\nGenerates an HTTP or WebSocket middleware class registered in the target module. Automatically installs `@ooneex/middleware`:\n\n```bash\noo make:middleware --name Auth --module user\noo make:middleware --name Auth --module user --isSocket\n```\n\n**Why:** Cross-cutting concerns like authentication, CORS, request logging, and input sanitisation should not live inside controllers. Middleware classes intercept requests before they reach a controller, keeping that logic reusable and independently testable.\n\n**Benefits:** Reusable across multiple controllers within the module, auto-registered in the middleware pipeline, full access to injected services via DI, works identically for HTTP and WebSocket routes.\n\n**Good practices:**\n- Keep middleware single-purpose (e.g. `AuthMiddleware` only handles authentication, not rate limiting).\n- Always call `next()` explicitly or return a response \u2014 never leave the pipeline hanging.\n- Order matters: authentication middleware must run before authorisation middleware.\n- Avoid heavy computation in middleware; defer expensive work to the service layer.\n- Write unit tests that verify the middleware passes, blocks, and modifies requests as expected.\n\n---\n\n### Permission\n\nGenerates a permission class in `modules/<name>/src/permissions/<Name>Permission.ts`. Automatically installs `@ooneex/permission`:\n\n```bash\noo make:permission --name User --module user\n```\n\n**Why:** Scattering permission checks across controllers and services leads to inconsistency and makes auditing access control difficult. A dedicated permission class per domain centralises all access rules for that domain in one reviewable place.\n\n**Benefits:** All permissions for a domain are discoverable in a single file, easy to audit who can do what, permissions can be reused across multiple controllers without duplication, changes to access rules require touching only one class.\n\n**Good practices:**\n- Name permissions after the action and resource (e.g. `UserPermission` checks `canCreate`, `canUpdate`, `canDelete`).\n- Always check permissions in middleware or the service layer \u2014 never in the entity or repository.\n- Combine with roles (RBAC) for coarse-grained access and permissions for fine-grained control.\n- Write tests that assert both allowed and denied cases for every permission rule.\n- Never hardcode user IDs or emails inside permission logic; use roles and attributes instead.\n\n---\n\n### PubSub\n\nGenerates a pub/sub event class in `modules/<name>/src/events/<Name>Event.ts` and registers it in the module. Automatically installs `@ooneex/pub-sub`:\n\n```bash\noo make:pubsub --name UserCreated --module user\noo make:pubsub --name UserCreated --module user --channel user-created\n```\n\n**Why:** Direct calls between modules create tight coupling that makes the codebase fragile and hard to extend. Pub/sub events decouple the publisher from the subscriber: the `user` module emits `UserCreated` without knowing or caring which other modules react to it.\n\n**Benefits:** Loose coupling between modules, multiple subscribers can react to the same event independently, easy to add new reactions without modifying the publisher, events are named and typed so their contracts are explicit.\n\n**Good practices:**\n- Name events in the past tense (e.g. `UserCreated`, `OrderShipped`) to make clear they describe something that already happened.\n- Keep event payloads small and serialisable \u2014 include IDs rather than full entity objects where possible.\n- Subscribe in the module that owns the reaction, not in the module that owns the event.\n- Make event handlers idempotent: the same event may be delivered more than once in failure scenarios.\n- Log every event published and consumed to simplify debugging distributed flows.\n\n---\n\n### Repository\n\nGenerates a repository class for data access in `modules/<name>/src/repositories/<Name>Repository.ts`. Automatically installs `@ooneex/repository`:\n\n```bash\noo make:repository --name User --module user\n```\n\n**Why:** Putting database queries directly in services mixes business logic with persistence concerns and makes services impossible to test without a database. The repository pattern isolates all data-access code behind a typed interface that can be mocked in tests.\n\n**Benefits:** Services remain database-agnostic, all queries for an entity are discoverable in one class, easy to swap the underlying ORM or database without touching business logic, clean boundary for unit testing.\n\n**Good practices:**\n- One repository per entity (e.g. `UserRepository` owns all queries against the `users` table).\n- Repositories should only contain query logic \u2014 no business rules, no validation, no event publishing.\n- Use descriptive method names that reflect intent (e.g. `findActiveByEmail`, `findExpiredTokens`) rather than generic `find` with complex filter objects.\n- Return domain objects or plain data \u2014 never expose raw ORM query builders to callers.\n- Add pagination to any method that can return an unbounded number of rows.\n\n---\n\n### Service\n\nGenerates a service class in `modules/<name>/src/services/<Name>Service.ts`. Automatically installs `@ooneex/service`:\n\n```bash\noo make:service --name User --module user\n```\n\n**Why:** Business logic scattered across controllers is impossible to test, reuse, or reason about. Services are the home of all business rules, orchestrating repositories, events, and other services in a single, testable unit.\n\n**Benefits:** Business logic is testable without HTTP, reusable across multiple controllers or cron jobs, dependencies are explicit via constructor injection, easy to mock at the service boundary in integration tests.\n\n**Good practices:**\n- One service per aggregate or major business capability (e.g. `UserService` for user lifecycle, `BillingService` for payment flows).\n- Services should call repositories for data, never query the database directly.\n- Keep services stateless \u2014 all required data should come from method arguments or injected dependencies.\n- Raise typed exceptions (e.g. `UserNotFoundException`) rather than returning `null` or error codes.\n- A service method should do one thing; if a method grows beyond ~20 lines, consider extracting a helper or sub-service.\n\n---\n\n### Storage\n\nGenerates a file storage class in `modules/<name>/src/storage/<Name>Storage.ts`. Automatically installs `@ooneex/storage`:\n\n```bash\noo make:storage --name Avatar --module user\n```\n\n**Why:** Coupling file upload logic directly to a specific provider (S3, Cloudflare R2, local filesystem) makes it painful to change backends and duplicates configuration across the codebase. A storage class abstracts the provider behind a consistent interface scoped to a specific asset type.\n\n**Benefits:** Provider-agnostic uploads and reads, all storage configuration for an asset type in one class, easy to switch between local filesystem (development) and cloud storage (production) via environment variables, consistent file-naming and path conventions.\n\n**Good practices:**\n- Name storage classes after the asset they manage (e.g. `AvatarStorage`, `InvoiceStorage`).\n- Always validate file type and size before passing to the storage class \u2014 never trust client-supplied content types.\n- Generate deterministic, collision-resistant file names (e.g. `{userId}/{uuid}.{ext}`) rather than using the original filename.\n- Never store the full URL in the database \u2014 store only the path or key and derive the URL at read time so it works across environments.\n- Delete orphaned files when the associated entity is deleted to avoid unbounded storage growth.\n\n---\n\n### Vector Database\n\nGenerates a vector database class in `modules/<name>/src/databases/<Name>VectorDatabase.ts`. Automatically installs `@ooneex/rag`:\n\n```bash\noo make:vector-database --name Knowledge --module user\n```\n\n**Why:** Semantic search and Retrieval-Augmented Generation (RAG) require storing and querying high-dimensional embeddings, which relational databases are not designed for. A dedicated vector database class encapsulates the embedding model, index configuration, and similarity-search logic in one place.\n\n**Benefits:** Centralised embedding and retrieval strategy per knowledge domain, easy to swap vector backends (pgvector, Qdrant, etc.), consistent chunking and metadata conventions, decoupled from the LLM layer so both can evolve independently.\n\n**Good practices:**\n- One vector database class per knowledge domain (e.g. `KnowledgeVectorDatabase`, `ProductCatalogVectorDatabase`).\n- Always store the source document ID alongside each embedding so retrieved chunks can be traced back to their origin.\n- Use a consistent chunking strategy (fixed-size or sentence-boundary) within a class \u2014 mixing strategies pollutes the index.\n- Re-index when the embedding model changes; embeddings from different models are not comparable.\n- Cache frequently retrieved embeddings to avoid redundant model calls on hot queries.\n\n---\n\n## Claude\n\nThis project ships with a set of **Claude Code skills** \u2014 pre-built instruction sets that tell Claude exactly how to scaffold, implement, and test each type of artefact in this codebase. Skills eliminate the gap between \"generate the files\" and \"ship working code\": each skill runs the CLI generator, reads the output, completes the implementation, writes tests, and lints \u2014 all in one `/command`.\n\n### Why Skills?\n\nRunning `oo make:service` creates a skeleton. A Claude skill does that *and* completes the business logic, writes a meaningful test suite, applies coding conventions, and formats the result \u2014 turning a 10-step workflow into a single prompt.\n\n**Benefits:**\n- Consistent code quality across every artefact, regardless of who wrote it\n- Conventions (visibility modifiers, naming suffixes, DI patterns) are enforced automatically\n- Tests are generated alongside implementation, not as an afterthought\n- Skills chain together \u2014 `make:controller` automatically triggers `make:service` and `make:pubsub`\n\n### Setup\n\nBefore using skills, generate the `.claude/` directory with all skill files and the project `CLAUDE.md`:\n\n```bash\noo claude:skill:create\n```\n\nThis writes `.claude/CLAUDE.md` and one `SKILL.md` per skill under `.claude/skills/<skill-name>/`. Re-run any time you upgrade the CLI to pick up new or updated skills. Commit the generated files so every team member gets the same skill definitions without running the command themselves.\n\n### How to Use\n\nOpen Claude Code in the project root and type `/skill-name`. Claude will execute the full workflow described in the skill. You can pass arguments inline:\n\n```\n/make:service --name=UserCreate --module=user\n/make:controller --name=UserCreate --module=user --route.path=/users --route.method=POST\n/commit\n```\n\nIf you omit arguments, Claude will prompt you for the required values.\n\n> **Important:** Always run skills from the project root, not from inside a module directory.\n\n### Available Skills\n\n#### Code Quality\n\n| Skill | Description |\n|---|---|\n| `/optimize` | Enforce naming conventions, remove duplication, improve performance, and restructure tests across a module |\n| `/commit` | Analyze staged changes, group them by module, and create properly scoped conventional commits |\n\n#### Generators\n\n| Skill | Description |\n|---|---|\n| `/make:ai` | Generate an AI integration class with `run` and `runStream` methods, wired to `@ooneex/ai` |\n| `/make:analytics` | Generate an analytics handler class for tracking domain events via `@ooneex/analytics` |\n| `/make:cache` | Generate a cache handler class with key and TTL management via `@ooneex/cache` |\n| `/make:command` | Generate a CLI command class implementing `ICommand` via `@ooneex/cli` |\n| `/make:controller` | Generate an HTTP or WebSocket controller with route type, validation, roles, service, and pub/sub event |\n| `/make:cron` | Generate a cron job class registered in its module via `@ooneex/cron` |\n| `/make:database` | Generate a database adapter class for raw queries via `@ooneex/database` |\n| `/make:entity` | Generate a TypeORM entity class registered in `SharedModule` via `@ooneex/entity` |\n| `/make:logger` | Generate a structured logger class with domain context via `@ooneex/logger` |\n| `/make:mailer` | Generate a mailer class and its JSX email template via `@ooneex/mailer` |\n| `/make:middleware` | Generate an HTTP or WebSocket middleware class registered in the module via `@ooneex/middleware` |\n| `/make:permission` | Generate a permission class centralising access rules for a domain via `@ooneex/permission` |\n| `/make:pubsub` | Generate a pub/sub event class registered in the module via `@ooneex/pub-sub` |\n| `/make:repository` | Generate a repository class for typed data access via `@ooneex/repository` |\n| `/make:service` | Generate a service class implementing `IService` with business logic and tests |\n| `/make:storage` | Generate a file storage class for asset management via `@ooneex/storage` |\n| `/make:vector-database` | Generate a vector database class for semantic search and RAG via `@ooneex/rag` |\n\n#### Database\n\n| Skill | Description |\n|---|---|\n| `/migration:create` | Generate a migration file with `up`/`down` methods, index guidance, and structural tests |\n| `/seed:create` | Generate a seed class and its YAML data file with idempotent insertion logic |\n\n#### Spec\n\n| Skill | Description |\n|---|---|\n| `/spec:plan` | Parse user-provided content and produce one `specs/<spec-name>.spec.yml` file per entity/action pair |\n| `/spec:implement` | Read a single spec YML entry and implement entity, repository, service, controller/command, and optional resources |\n\n### Coding Conventions Enforced by Skills\n\nAll generator skills automatically apply the conventions defined in `/optimize`:\n\n- **Visibility modifiers** \u2014 every class method and property has explicit `public`, `private`, or `protected`\n- **Naming suffixes** \u2014 types end with `Type`, interfaces start with `I`\n- **Arrow functions** \u2014 used everywhere except class methods\n- **No non-null assertions** \u2014 use default values or optional types instead\n- **Dependency injection** \u2014 constructor injection via `@inject()` from `@ooneex/container`\n- **Code hygiene** \u2014 no unused imports, no dead code, no bare `TODO` comments\n\n---\n\n## Release\n\n```bash\noo make:release\n```\n\nScans every `packages/` and `modules/` directory for unreleased conventional commits and, for each one that has them, performs a full release cycle automatically:\n\n1. **Detects unreleased work** \u2014 finds the last git tag matching `<package-name>@*` and lists all conventional commits that have landed since then in that directory. Packages with no new commits are skipped.\n2. **Bumps the version** in `package.json`:\n   - `minor` (e.g. `1.2.0 \u2192 1.3.0`) when any commit is of type `feat`\n   - `patch` (e.g. `1.2.0 \u2192 1.2.1`) for all other types (`fix`, `refactor`, `perf`, `docs`, `chore`, \u2026)\n3. **Updates `CHANGELOG.md`** with a dated version section. Commits are grouped into standard Keep-a-Changelog categories and linked to their SHA on the remote:\n\n   | Commit type | Changelog category |\n   |---|---|\n   | `feat` | Added |\n   | `fix` | Fixed |\n   | `refactor`, `perf`, `style`, `docs`, `build`, `ci`, `chore` | Changed |\n   | `revert` | Removed |\n\n4. **Creates a release commit** \u2014 stages `package.json` and `CHANGELOG.md` then commits with the message `chore(release): <name>@<version>`.\n5. **Creates an annotated git tag** \u2014 `<name>@<version>` (e.g. `@acme/user@1.3.0`).\n6. **Prompts to push** \u2014 after all packages are processed, asks whether to push commits and tags to the remote. If confirmed, it also runs `bun install`, commits the updated `bun.lock`, and pushes everything.\n\n> **Note:** This command requires conventional commits (`type(scope): Subject`). Non-conventional commits are silently ignored when building the changelog.\n\n---\n\n## Scripts\n\n| Command | Description |\n|---|---|\n| `bun run fmt` | Format all source files with Biome |\n| `bun run lint` | Lint all modules with Biome and TypeScript |\n| `bun run test` | Run tests across all modules |\n| `bun run commit` | Interactive conventional commit prompt |\n";
 
 // src/templates/app/tsconfig.json.txt
 var tsconfig_json_default = `{
@@ -9993,9 +9993,6 @@ A spec YML looks like:
 name: "organization.create"
 entity: "organization"
 description: "Admin creates a new organization"
-fields:
-  name: ""
-  type: "b2b|school|internal"
 roles:
   - super_admin
   - admin
@@ -10011,7 +10008,6 @@ Extract:
 - \`name\` \u2014 dot-notation identifier (e.g. \`"user.create"\`)
 - \`entity\` \u2014 the resource being acted on (e.g. \`"user"\`)
 - \`description\` \u2014 what the spec does
-- \`fields\` \u2014 map of field names to default values or pipe-separated enum variants
 - \`roles\` \u2014 list of roles with access
 - \`permissions\` \u2014 list of objects with \`name\` (\`"entity:action"\` format) and optional \`description\`
 
@@ -10033,12 +10029,6 @@ Determine whether a controller (HTTP) or command (CLI) is needed from the spec c
 /make:entity --name=<PascalEntity> --module=<module>
 \`\`\`
 
-Map each key in \`fields\` to a typed column:
-- A pipe-separated value (e.g. \`"b2b|school|internal"\`) \u2192 enum column with those variants.
-- An empty string \u2192 \`string\` column.
-- A numeric value \u2192 \`number\` column.
-- A boolean value \u2192 \`boolean\` column.
-
 ### 4. Create or update the repository
 
 \`\`\`
@@ -10077,22 +10067,24 @@ Inject the service into the command. Set \`getName()\` to \`"<entity>:<action>"\
 
 ### 7. Create or update optional resources
 
-Inspect the spec description, fields, and entity context. Apply each applicable skill:
-
-| Resource          | Trigger condition                                              | Skill                   |
-|-------------------|----------------------------------------------------------------|-------------------------|
-| \`permission\`      | Spec has \`roles\` or \`permissions\` defined                      | \`/make:permission\`      |
-| \`middleware\`      | Spec implies auth, rate-limiting, or request transformation    | \`/make:middleware\`      |
-| \`cache\`           | Spec implies read-heavy or list endpoints                      | \`/make:cache\`           |
-| \`pubsub\`          | Spec mutates state (\`post\`, \`put\`, \`patch\`, \`delete\` routes)   | \`/make:pubsub\`          |
-| \`mailer\`          | Spec description mentions email, notification, or invitation   | \`/make:mailer\`          |
-| \`logger\`          | Spec description mentions audit, log, or traceability          | \`/make:logger\`          |
-| \`analytics\`       | Spec description mentions tracking, metrics, or reporting      | \`/make:analytics\`       |
-| \`storage\`         | Spec description mentions file, upload, or attachment          | \`/make:storage\`         |
-| \`cron\`            | Spec description mentions scheduled, periodic, or background   | \`/make:cron\`            |
-| \`ai\`              | Spec description mentions AI, embedding, or generation         | \`/make:ai\`              |
-| \`database\`        | Spec implies a new database connection or datasource           | \`/make:database\`        |
-| \`vector-database\` | Spec description mentions vector search or similarity          | \`/make:vector-database\` |
+Inspect the spec description and entity context. Apply each applicable skill.
+
+All optional resources are named using \`<PascalSpec>\` (derived from \`name\`, not \`entity\`). For example, spec name \`organization.read\` \u2192 \`<PascalSpec>\` = \`OrganizationRead\`, producing \`OrganizationReadPermission\`, \`OrganizationReadMiddleware\`, \`OrganizationReadCache\`, etc.
+
+| Resource          | Trigger condition                                              | Skill                                                            |
+|-------------------|----------------------------------------------------------------|------------------------------------------------------------------|
+| \`permission\`      | Spec has \`roles\` or \`permissions\` defined                      | \`/make:permission --name=<PascalSpec> --module=<module>\`         |
+| \`middleware\`      | Spec implies auth, rate-limiting, or request transformation    | \`/make:middleware --name=<PascalSpec> --module=<module>\`         |
+| \`cache\`           | Spec implies read-heavy or list endpoints                      | \`/make:cache --name=<PascalSpec> --module=<module>\`              |
+| \`pubsub\`          | Spec mutates state (\`post\`, \`put\`, \`patch\`, \`delete\` routes)   | \`/make:pubsub --name=<PascalSpec> --module=<module>\`             |
+| \`mailer\`          | Spec description mentions email, notification, or invitation   | \`/make:mailer --name=<PascalSpec> --module=<module>\`             |
+| \`logger\`          | Spec description mentions audit, log, or traceability          | \`/make:logger --name=<PascalSpec> --module=<module>\`             |
+| \`analytics\`       | Spec description mentions tracking, metrics, or reporting      | \`/make:analytics --name=<PascalSpec> --module=<module>\`          |
+| \`storage\`         | Spec description mentions file, upload, or attachment          | \`/make:storage --name=<PascalSpec> --module=<module>\`            |
+| \`cron\`            | Spec description mentions scheduled, periodic, or background   | \`/make:cron --name=<PascalSpec> --module=<module>\`               |
+| \`ai\`              | Spec description mentions AI, embedding, or generation         | \`/make:ai --name=<PascalSpec> --module=<module>\`                 |
+| \`database\`        | Spec implies a new database connection or datasource           | \`/make:database --name=<PascalSpec> --module=<module>\`           |
+| \`vector-database\` | Spec description mentions vector search or similarity          | \`/make:vector-database --name=<PascalSpec> --module=<module>\`    |
 
 ### 8. Lint and format
 
@@ -10157,20 +10149,13 @@ For each spec, populate the following fields:
 
 **\`entity\`** \u2014 the resource name in snake_case (e.g. \`"blog_post"\`).
 
-**\`description\`** \u2014 one sentence describing what the operation does, derived from the user content.
-
-**\`fields\`** \u2014 map of field names to their default value or pipe-separated enum variants:
-- Free text / unknown type \u2192 \`""\`
-- Numeric \u2192 \`0\`
-- Boolean \u2192 \`false\`
-- Enum choices \u2192 \`"choice_a|choice_b|choice_c"\`
-- Omit fields that are not relevant to this specific action (e.g. no \`password\` field on a \`.read\` spec).
+**\`description\`** \u2014 describes what the operation does, the data it acts on, and any key business rules or constraints an implementer must know. Derived from the user content.
 
 **\`roles\`** \u2014 list of role identifiers that may perform this operation. Derive from the user content; default to \`["user"]\` when not specified.
 
-**\`permissions\`** \u2014 list of objects with:
-- \`name\`: \`"<entity>:<action>"\` format (e.g. \`"blog_post:create"\`)
-- \`description\`: short sentence (may be empty string when obvious)
+**\`permissions\`** \u2014 list of fine-grained access-control entries that guard this operation. Each object has:
+- \`name\`: \`"<entity>:<action>"\` format (e.g. \`"blog_post:create"\`) \u2014 uniquely identifies the permission across the system
+- \`description\`: one sentence explaining what this permission grants, who it protects, and any conditions or limits (e.g. ownership, tenant scope). Required \u2014 never leave empty.
 
 ### 4. Write spec files
 
@@ -10181,14 +10166,12 @@ Write one YAML block per file using the structure below. Do **not** combine mult
 \`\`\`yaml
 name: "<entity>.<action>"
 entity: "<entity>"
-description: "<one-sentence description>"
-fields:
-  <field_name>: <description>
+description: "<description of what the operation does, the data it acts on, and any key business rules or constraints an implementer must know>"
 roles:
   - <role>
 permissions:
   - name: "<entity>:<action>"
-    description: "<optional description>"
+    description: "<what this permission grants, who it protects, and any conditions or limits>"
 \`\`\`
 
 Create the \`specs/\` directory if it does not exist.
@@ -10205,7 +10188,6 @@ After all files are written, report:
 
 - One file per spec \u2014 never merge multiple specs into one file.
 - Derive everything from the user content; never ask for values that can be inferred.
-- Keep \`fields\` minimal and action-appropriate: a \`.delete\` spec typically has no fields; a \`.list\` spec may have filter fields only.
 - If the user content implies a CLI operation rather than an HTTP endpoint, add \`kind: command\` at the top level of the spec.
 - Specs are consumed by \`/spec:implement\` \u2014 keep field names and values precise so that skill can infer types without ambiguity.
 `;
@@ -93926,7 +93908,7 @@ var issueToYaml = (issue) => {
   if (issue.comments && issue.comments.length > 0) {
     lines.push("comments:");
     for (const comment of issue.comments) {
-      lines.push(`  - body: ${q3(comment.body)}`);
+      lines.push(`  - ${q3(comment.body)}`);
     }
   }
   return `${lines.join(`
@@ -108633,4 +108615,4 @@ SeedRunCommand = __legacyDecorateClassTS([
 // src/index.ts
 await run();
 
-//# debugId=7FD9E57E31842BBE64756E2164756E21
+//# debugId=7B1CD7ECD490FD4464756E2164756E21