@venizia/ignis-docs 0.0.8 → 0.1.0

package/content/best-practices/code-style-standards/function-patterns.md

@@ -55,13 +55,13 @@ Use consistent prefixes based on function purpose:
 | Prefix | Purpose | Examples |
 |--------|---------|----------|
 | `generate*` | Create column definitions / schemas | `generateIdColumnDefs()`, `generateTzColumnDefs()` |
-| `build*` | Construct complex objects | `buildPrimitiveCondition()`, `buildJsonOrderBy()` |
-| `to*` | Convert/transform data | `toCamel()`, `toBoolean()`, `toStringDecimal()` |
+| `build*` | Construct complex objects | `buildValueCondition()`, `buildJsonOrderBy()` |
+| `to*` | Convert/transform data | `toCamel()`, `toBoolean()` |
 | `is*` | Boolean validation/check | `isWeekday()`, `isInt()`, `isFloat()`, `isPromiseLike()` |
 | `extract*` | Pull out specific parts | `extractTimestamp()`, `extractWorkerId()`, `extractSequence()` |
 | `enrich*` | Enhance with additional data | `enrichUserAudit()`, `enrichWithMetadata()` |
 | `get*` | Retrieve/fetch data | `getSchema()`, `getConnector()`, `getError()` |
-| `resolve*` | Determine/compute value | `resolveValue()`, `resolvePath()` |
+| `resolve*` | Determine/compute value | `resolveValue()`, `resolveClass()` |
 
 **Examples:**
 
@@ -71,13 +71,12 @@ const idCols = generateIdColumnDefs({ id: { dataType: 'string' } });
 const tzCols = generateTzColumnDefs();
 
 // Builders - construct complex query objects
-const condition = buildPrimitiveCondition(column, operator, value);
+const condition = buildValueCondition(column, value);
 const orderBy = buildJsonOrderBy(schema, path, direction);
 
 // Converters - transform data types
 const camelCase = toCamel('snake_case');
 const bool = toBoolean('true');
-const decimal = toStringDecimal(123.456, 2);
 
 // Validators - boolean checks
 if (isWeekday(date)) { /* ... */ }
@@ -94,9 +93,9 @@ const workerId = extractWorkerId(snowflakeId);
 Every class extending a base class should set its scope using `ClassName.name`:
 
 ```typescript
-export class JWTTokenService extends BaseService {
+export class PaymentService extends BaseService {
   constructor() {
-    super({ scope: JWTTokenService.name });
+    super({ scope: PaymentService.name });
   }
 }
 
@@ -135,7 +134,7 @@ await executeWithPerformanceMeasure({
     await syncAllUsers();
   },
 });
-// Logs: [DataSync] Sync user records | Took: 1234.56 (ms)
+// Logs: [DataSync] DONE | Sync user records | Took: 1234.56 (ms)
 ```
 
 **Method-scoped logging pattern:**
@@ -144,13 +143,13 @@ await executeWithPerformanceMeasure({
 class UserService {
   private logger = Logger.get('UserService');
 
-  async createUser(data: CreateUserDto) {
+  async createUser(data: TCreateUserRequest) {
     // Use .for() to add method context to all logs
     this.logger.for('createUser').info('Creating user: %j', data);
     // Output: [UserService-createUser] Creating user: {...}
 
     try {
-      const user = await this.userRepo.create({ data });
+      const { data: user } = await this.userRepository.create({ data });
       this.logger.for('createUser').info('User created: %s', user.id);
       return user;
     } catch (error) {

package/content/best-practices/code-style-standards/index.md

@@ -1,6 +1,6 @@
 # Code Style Standards
 
-Maintain consistent code style using **Prettier** (formatting) and **ESLint** (code quality). Ignis provides centralized configurations via the `@venizia/dev-configs` package.
+Maintain consistent code style using **Prettier** (formatting) and **ESLint** (code quality). IGNIS provides centralized configurations via the `@venizia/dev-configs` package.
 
 ## Quick Reference
 

package/content/best-practices/code-style-standards/naming-conventions.md

@@ -57,9 +57,9 @@ export * from './types';
 |------|---------|---------|
 | Components | `[Feature]Component` | `HealthCheckComponent`, `AuthComponent` |
 | Controllers | `[Feature]Controller` | `UserController`, `AuthController` |
-| Services | `[Feature]Service` | `JWTTokenService`, `PaymentService` |
+| Services | `[Feature]Service` | `JWSTokenService`, `PaymentService` |
 | Repositories | `[Feature]Repository` | `UserRepository`, `OrderRepository` |
-| Strategies | `[Feature]Strategy` | `JWTAuthenticationStrategy` |
+| Strategies | `[Feature]Strategy` | `JWSAuthenticationStrategy`, `BasicAuthenticationStrategy` |
 | Factories | `[Feature]Factory` | `UIProviderFactory` |
 
 ## File Names
@@ -90,15 +90,17 @@ interface IHealthCheckOptions {
 }
 
 interface IAuthService {
-  signIn(context: Context): Promise<void>;
+  signIn(context: Context, opts: TSignInRequest): Promise<AnyObject>;
 }
 
 // Type aliases use 'T' prefix
 type TSignInRequest = z.infer<typeof SignInRequestSchema>;
-type TRouteContext = Context<Env, Path, Input>;
+type TAuthStrategy = TConstValue<typeof AuthenticateStrategy>;
 
 // Generic constraints
-type TTableSchemaWithId = { id: PgColumn };
+type TTableSchemaWithId<TC extends TableConfig = TableConfig> = PgTable<TC> & {
+  id: TIdColumn;
+};
 ```
 
 ## Binding Keys
@@ -123,14 +125,14 @@ Use underscore prefix (`_`) for private and protected class fields to distinguis
 ```typescript
 class MyRepository extends DefaultCRUDRepository {
   // Private fields with underscore prefix
-  private _dataSource: IDataSource;
-  private _entity: BaseEntity;
+  private _dataSource: AbstractDataSource;
+  private _entity: AbstractEntity;
   private _hiddenProperties: Set<string> | null = null;
 
   // Protected fields also use underscore prefix
   protected _schemaFactory?: ReturnType<typeof createSchemaFactory>;
 
-  constructor(dataSource: IDataSource) {
+  constructor(dataSource: AbstractDataSource) {
     // 'dataSource' (param) vs '_dataSource' (field)
     this._dataSource = dataSource;
   }

package/content/best-practices/code-style-standards/route-definitions.md

@@ -1,6 +1,6 @@
 # Route Definitions
 
-Ignis supports multiple methods for defining routes. Choose based on your needs.
+IGNIS supports multiple methods for defining routes. Choose based on your needs.
 
 ## Method 1: Config-Driven Routes
 
@@ -15,12 +15,14 @@ export class UserRestPaths {
 }
 
 // common/route-configs.ts
+// jsonResponse({ schema }) expands to a 200 response plus a '4xx | 5xx' error fallback
 export const RouteConfigs = {
   GET_USERS: {
     method: HTTP.Methods.GET,
     path: UserRestPaths.ROOT,
     responses: jsonResponse({
-      [HTTP.ResultCodes.RS_2.Ok]: UserListSchema,
+      description: 'List of users',
+      schema: UserListSchema,
     }),
   },
   GET_USER_BY_ID: {
@@ -30,8 +32,8 @@ export const RouteConfigs = {
       params: z.object({ id: z.string() }),
     },
     responses: jsonResponse({
-      [HTTP.ResultCodes.RS_2.Ok]: UserSchema,
-      [HTTP.ResultCodes.RS_4.NotFound]: ErrorSchema,
+      description: 'User detail',
+      schema: UserSchema,
     }),
   },
 } as const;
@@ -42,6 +44,9 @@ export const RouteConfigs = {
 ```typescript
 @controller({ path: '/users' })
 export class UserController extends BaseRestController {
+  constructor() {
+    super({ scope: UserController.name });
+  }
 
   @api({ configs: RouteConfigs.GET_USERS })
   list(context: TRouteContext) {
@@ -58,14 +63,18 @@ export class UserController extends BaseRestController {
 
 ## Method 3: Using `bindRoute` (Programmatic)
 
+Register routes in the `binding()` lifecycle method:
+
 ```typescript
 @controller({ path: '/health' })
 export class HealthCheckController extends BaseRestController {
   constructor() {
     super({ scope: HealthCheckController.name });
+  }
 
+  override binding(): ValueOrPromise<void> {
     this.bindRoute({ configs: RouteConfigs.GET_HEALTH }).to({
-      handler: context => context.json({ status: 'ok' }),
+      handler: context => context.json({ status: 'ok' }, HTTP.ResultCodes.RS_2.Ok),
     });
   }
 }
@@ -78,11 +87,13 @@ export class HealthCheckController extends BaseRestController {
 export class HealthCheckController extends BaseRestController {
   constructor() {
     super({ scope: HealthCheckController.name });
+  }
 
+  override binding(): ValueOrPromise<void> {
     this.defineRoute({
       configs: RouteConfigs.POST_PING,
       handler: context => {
-        const { message } = context.req.valid('json');
+        const { message } = context.req.valid<{ message: string }>('json');
         return context.json({ echo: message }, HTTP.ResultCodes.RS_2.Ok);
       },
     });
@@ -124,6 +135,8 @@ const UserSchema = z.object({
 ## Request Validation
 
 ```typescript
+// Use an explicit status-code map (with jsonContent) when the success
+// code is not 200 - jsonResponse() always keys the success response at 200
 export const RouteConfigs = {
   CREATE_USER: {
     method: HTTP.Methods.POST,
@@ -134,11 +147,16 @@ export const RouteConfigs = {
         description: 'User data',
       }),
     },
-    responses: jsonResponse({
-      [HTTP.ResultCodes.RS_2.Created]: UserSchema,
-      [HTTP.ResultCodes.RS_4.BadRequest]: ErrorSchema,
-      [HTTP.ResultCodes.RS_4.Conflict]: ErrorSchema,
-    }),
+    responses: {
+      [HTTP.ResultCodes.RS_2.Created]: jsonContent({
+        description: 'Created user',
+        schema: UserSchema,
+      }),
+      ['4xx | 5xx']: jsonContent({
+        description: 'Error Response',
+        schema: ErrorSchema,
+      }),
+    },
   },
 } as const;
 ```
@@ -147,4 +165,4 @@ export const RouteConfigs = {
 
 - [API Usage Examples](../api-usage-examples) - Full API patterns
 - [Controllers Reference](../../references/base/controllers) - Controller API
-- [Swagger Component](../../extensions/components/swagger) - OpenAPI setup
+- [Swagger Component](../../extensions/components/api-reference) - OpenAPI setup

package/content/best-practices/code-style-standards/tooling.md

@@ -1,6 +1,6 @@
 # Tooling Configuration
 
-Ignis provides centralized development configurations via the `@venizia/dev-configs` package.
+IGNIS provides centralized development configurations via the `@venizia/dev-configs` package.
 
 ## Installation
 
@@ -10,7 +10,7 @@ bun add -d @venizia/dev-configs
 
 This package provides:
 - **ESLint rules** - Pre-configured for Node.js/TypeScript projects
-- **Prettier settings** - Consistent formatting across all Ignis projects
+- **Prettier settings** - Consistent formatting across all IGNIS projects
 - **TypeScript configs** - Shared base and common configurations
 
 ## Prettier Configuration
@@ -29,8 +29,9 @@ export default prettierConfigs;
 | Setting | Value | Description |
 |---------|-------|-------------|
 | `bracketSpacing` | `true` | `{ foo: bar }` |
-| `singleQuote` | `false` | `"string"` (double quotes) |
+| `singleQuote` | `true` | `'string'` (single quotes) |
 | `printWidth` | `100` | Maximum line length |
+| `tabWidth` | `2` | 2-space indentation |
 | `trailingComma` | `'all'` | `[1, 2, 3,]` |
 | `arrowParens` | `'avoid'` | `x => x` not `(x) => x` |
 | `semi` | `true` | Semicolons required |
@@ -65,6 +66,7 @@ export default eslintConfigs;
 **Includes:**
 - Pre-configured rules for Node.js/TypeScript (via `@minimaltech/eslint-node`)
 - Disables `@typescript-eslint/no-explicit-any` by default
+- Enforces mandatory braces: `curly: ['error', 'all']` and `unicorn/switch-case-braces: ['error', 'always']`
 
 **Customization:**
 ```javascript
@@ -113,9 +115,10 @@ Use the centralized TypeScript configs:
 
 | Option | Value | Purpose |
 |--------|-------|---------|
-| `target` | `ES2022` | Modern JavaScript features |
-| `experimentalDecorators` | `true` | Required for Ignis decorators |
+| `target` | `ES2024` | Modern JavaScript features |
+| `experimentalDecorators` | `true` | Required for IGNIS decorators |
 | `emitDecoratorMetadata` | `true` | Metadata reflection for DI |
+| `useDefineForClassFields` | `false` | Decorator-compatible class fields |
 | `strict` | `true` | Strict type checking |
 | `skipLibCheck` | `true` | Faster compilation |
 

package/content/best-practices/code-style-standards/type-safety.md

@@ -77,16 +77,17 @@ type RouteKey = keyof typeof RouteConfigs; // 'GET_USERS' | 'GET_USER_BY_ID'
 
 ```typescript
 export class DefaultCRUDRepository<
-  Schema extends TTableSchemaWithId = TTableSchemaWithId
+  EntitySchema extends TTableSchemaWithId = TTableSchemaWithId
 > {
-  // Schema is constrained to have an 'id' column
+  // EntitySchema is constrained to have an 'id' column
 }
 
 export interface IAuthService<
+  E extends Env = Env,
   SIRQ extends TSignInRequest = TSignInRequest,
   SIRS = AnyObject,
 > {
-  signIn(context: Context, opts: SIRQ): Promise<SIRS>;
+  signIn(context: TContext<E>, opts: SIRQ): Promise<SIRS>;
 }
 ```
 
@@ -96,21 +97,21 @@ Use TypeScript method overloads when return types depend on input options:
 
 ```typescript
 class Repository<T, R> {
-  // Overload 1: shouldReturn: false → data is null
-  create(opts: { data: T; options: { shouldReturn: false } }): Promise<{ count: number; data: null }>;
+  // Overload 1: shouldReturn: false → no data returned
+  create(opts: { data: T; options: { shouldReturn: false } }): Promise<{ count: number; data: undefined | null }>;
   // Overload 2: shouldReturn: true (default) → data is R
   create(opts: { data: T; options?: { shouldReturn?: true } }): Promise<{ count: number; data: R }>;
   // Implementation signature
-  create(opts: { data: T; options?: { shouldReturn?: boolean } }): Promise<{ count: number; data: R | null }> {
+  create(opts: { data: T; options?: { shouldReturn?: boolean } }): Promise<{ count: number; data: R | undefined | null }> {
     // implementation
   }
 }
 
 // Usage
-const result1 = await repo.create({ data: user, options: { shouldReturn: false } });
-// result1.data is typed as null
+const result1 = await userRepository.create({ data: user, options: { shouldReturn: false } });
+// result1.data is typed as undefined | null
 
-const result2 = await repo.create({ data: user });
+const result2 = await userRepository.create({ data: user });
 // result2.data is typed as R (the entity type)
 ```
 
@@ -151,10 +152,10 @@ function processResult<T>(result: TResult<T>) {
   if (result.success) {
     // TypeScript knows result.data exists
     return result.data;
-  } else {
-    // TypeScript knows result.error exists
-    throw new Error(result.error);
   }
+
+  // TypeScript knows result.error exists
+  throw getError({ message: result.error });
 }
 ```
 

package/content/best-practices/common-pitfalls.md

@@ -1,6 +1,6 @@
 # Common Pitfalls
 
-Avoid these common mistakes when building Ignis applications.
+Avoid these common mistakes when building IGNIS applications.
 
 ## 1. Forgetting to Register Resources
 
@@ -55,7 +55,7 @@ export class Application extends BaseApplication {
 })
 
 // ❌ BAD - typo in string (note: "Repository" is misspelled)
-@inject({ key: 'repositories.ConfigurationRepository' })
+@inject({ key: 'repositories.ConfigurationRepositry' })
 ```
 
 ## 3. Business Logic in Controllers
@@ -66,7 +66,7 @@ export class Application extends BaseApplication {
 
 -   **Bad:**
     ```typescript
-    import { ApplicationError, getError } from '@venizia/ignis-helpers';
+    import { getError, HTTP } from '@venizia/ignis-helpers';
 
     // In a Controller
     async createUser(c: Context) {
@@ -79,7 +79,9 @@ export class Application extends BaseApplication {
         }
         
         const company = await this.companyRepository.findOrCreate(companyName);
-        const user = await this.userRepository.create({ name, email, companyId: company.id });
+        const user = await this.userRepository.create({
+          data: { name, email, companyId: company.id },
+        });
         
         return c.json(user, HTTP.ResultCodes.RS_2.Ok);
     }
@@ -99,7 +101,7 @@ export class Application extends BaseApplication {
         // All the complex logic now resides in the service
         const existingUser = await this.userRepository.findByEmail(data.email);
         // ...
-        return await this.userRepository.create(...);
+        return await this.userRepository.create({ data });
     }
     ```
 
@@ -142,7 +144,7 @@ This ensures that the route configuration object is treated as a readonly litera
 
 **Problem:** Attempting to update or delete all records without an explicit `where` condition.
 
-**Solution:** Ignis prevents accidental bulk data destruction. You must either provide a `where` condition or explicitly set `force: true`.
+**Solution:** IGNIS prevents accidental bulk data destruction. You must either provide a `where` condition or explicitly set `force: true`.
 
 ```typescript
 // ❌ BAD - Will throw error
@@ -150,7 +152,8 @@ await userRepository.updateBy({
   data: { status: 'INACTIVE' },
   where: {},  // Empty where = targets ALL records
 });
-// Error: [updateBy] DENY to perform updateBy | Empty where condition
+// Error: [_update] Entity: User | DENY to perform update | Empty where condition
+// (updateBy is an alias that delegates to updateAll)
 
 // ✅ GOOD - Explicit where condition
 await userRepository.updateBy({
@@ -175,26 +178,27 @@ await userRepository.updateBy({
 
 **Error Message:**
 ```
-[UserRepository] Schema key mismatch | Entity name 'User' not found in connector.query | Available keys: [Configuration, Post]
+[UserRepository] Schema key mismatch | Entity name 'User' not found in connector.query | Available keys: [Configuration, Post] | Ensure the model's TABLE_NAME matches the schema registration key
 ```
 
-**Solution:** Ensure your entity class name matches the table name in `pgTable()`:
+**Solution:** The schema registration key follows the precedence `@model tableName metadata > static TABLE_NAME > class name`, while the repository looks the query interface up by the entity **class name**. Do not set `TABLE_NAME` (or `tableName` metadata) to a value that differs from the class name:
 
 ```typescript
-// ❌ BAD - Class name 'User' doesn't match table name 'users'
+// ❌ BAD - Schema is registered under 'users', but looked up as 'User'
 @model({ type: 'entity' })
-export class User extends BaseEntity<typeof User.schema> {
-  static override schema = pgTable('users', { /* ... */ });  // Lowercase 'users'
+export class User extends BasePostgresEntity<typeof User.schema> {
+  static override TABLE_NAME = 'users';  // Differs from class name!
+  static override schema = pgTable('User', { /* ... */ });
 }
 
-// ✅ GOOD - Class name matches table name
+// ✅ GOOD - No TABLE_NAME override; registration key defaults to the class name
 @model({ type: 'entity' })
-export class User extends BaseEntity<typeof User.schema> {
-  static override schema = pgTable('User', { /* ... */ });  // Matches class name
+export class User extends BasePostgresEntity<typeof User.schema> {
+  static override schema = pgTable('User', { /* ... */ });
 }
 ```
 
-**Why this matters:** The framework uses `entity.name` (class name) to look up the query interface in `connector.query`. If they don't match, the repository can't find its table.
+**Why this matters:** The framework uses `entity.name` (class name) to look up the query interface in `connector.query`, but registers the schema under the resolved table name. If they don't match, the repository can't find its table. The first argument of `pgTable()` is the physical SQL table name and is independent of this lookup - by convention it matches the class name.
 
 ## 8. Validation Error Response Structure
 
@@ -205,9 +209,12 @@ export class User extends BaseEntity<typeof User.schema> {
 ```json
 {
   "statusCode": 422,
-  "message": "ValidationError",
+  "message": "Invalid email",
+  "messageCode": "invalid_string",
   "requestId": "abc123",
   "details": {
+    "url": "http://localhost:3000/users",
+    "path": "/users",
     "cause": [
       {
         "path": "email",
@@ -252,10 +259,10 @@ try {
 
 ```typescript
 // ❌ BAD - Direct import causes circular dependency
-import { UserService } from './user.service';
+import { User } from './user.model';
 
 @model({ type: 'entity' })
-export class Order extends BaseEntity<typeof Order.schema> {
+export class Order extends BasePostgresEntity<typeof Order.schema> {
   static override relations = (): TRelationConfig[] => [
     { schema: User.schema, ... }, // User imports Order, Order imports User
   ];
@@ -263,7 +270,7 @@ export class Order extends BaseEntity<typeof Order.schema> {
 
 // ✅ GOOD - Lazy import breaks the cycle
 @model({ type: 'entity' })
-export class Order extends BaseEntity<typeof Order.schema> {
+export class Order extends BasePostgresEntity<typeof Order.schema> {
   static override relations = (): TRelationConfig[] => {
     const { User } = require('./user.model'); // Lazy require
     return [{ schema: User.schema, ... }];
@@ -283,15 +290,15 @@ export class Order extends BaseEntity<typeof Order.schema> {
 
 ```typescript
 // ❌ BAD - No error handling
-const tx = await repo.beginTransaction();
-await repo.create({ data, options: { transaction: tx } });
+const tx = await userRepository.beginTransaction();
+await userRepository.create({ data, options: { transaction: tx } });
 await tx.commit(); // If create fails, commit is never called but neither is rollback
 
 // ✅ GOOD - Proper transaction handling
-const tx = await repo.beginTransaction();
+const tx = await userRepository.beginTransaction();
 try {
-  await repo.create({ data, options: { transaction: tx } });
-  await otherRepo.update({ data: other, options: { transaction: tx } });
+  await userRepository.create({ data, options: { transaction: tx } });
+  await orderRepository.updateById({ id, data: other, options: { transaction: tx } });
   await tx.commit();
 } catch (error) {
   await tx.rollback();
@@ -342,40 +349,52 @@ async createOrder(c: Context) {
 
 **Problem:** Relations return empty arrays or `null` unexpectedly.
 
-**Cause:** Mismatch between `fields` and `references` in relation metadata.
+**Cause:** Mismatch between `fields` and `references` in relation metadata (or defining them on the wrong side).
 
-**Solution:** Double-check that foreign keys point to the correct columns:
+**Solution:** `fields`/`references` belong on the `RelationTypes.ONE` side (the entity holding the foreign key). The `RelationTypes.MANY` side only takes a `relationName` pointing at the matching `one` relation:
 
 ```typescript
-// ❌ BAD - fields and references swapped
+// ❌ BAD - fields and references swapped on the ONE side (on Post)
 static override relations = (): TRelationConfig[] => [
   {
-    name: 'posts',
-    type: RelationTypes.MANY,
-    schema: Post.schema,
+    name: 'author',
+    type: RelationTypes.ONE,
+    schema: User.schema,
     metadata: {
-      fields: [Post.schema.authorId],     // Wrong! This should be User.schema.id
-      references: [User.schema.id],        // Wrong! This should be Post.schema.authorId
+      fields: [User.schema.id],           // Wrong! This should be Post.schema.authorId
+      references: [Post.schema.authorId], // Wrong! This should be User.schema.id
     },
   },
 ];
 
 // ✅ GOOD - Correct configuration
-// "User has many Posts where User.id = Post.authorId"
+// On Post: "Post belongs to one User where Post.authorId = User.id"
+static override relations = (): TRelationConfig[] => [
+  {
+    name: 'author',
+    type: RelationTypes.ONE,
+    schema: User.schema,
+    metadata: {
+      fields: [Post.schema.authorId],  // Current entity's foreign key
+      references: [User.schema.id],    // Related entity's key
+    },
+  },
+];
+
+// On User: "User has many Posts" - MANY side references the one relation by name
 static override relations = (): TRelationConfig[] => [
   {
     name: 'posts',
     type: RelationTypes.MANY,
     schema: Post.schema,
     metadata: {
-      fields: [User.schema.id],            // Parent's key
-      references: [Post.schema.authorId],  // Child's foreign key
+      relationName: 'author', // Points to the 'one' relation name on Post
     },
   },
 ];
 ```
 
-**Rule of thumb:** `fields` is the key on the current entity, `references` is the key on the related entity.
+**Rule of thumb:** on the `ONE` side, `fields` is the foreign key on the current entity, `references` is the key on the related entity. The `MANY` side only names its inverse relation.
 
 ## 13. Overwriting Data with Partial Updates
 

package/content/best-practices/contribution-workflow.md

@@ -1,6 +1,6 @@
 # Contribution Workflow
 
-Guidelines for contributing to Ignis - help us maintain quality and streamline the process.
+Guidelines for contributing to IGNIS - help us maintain quality and streamline the process.
 
 ## Git Branching Strategy
 
@@ -42,7 +42,7 @@ git remote add upstream https://github.com/VENIZIA-AI/ignis.git
 
 ## Package Build Order
 
-Ignis is a monorepo with interdependent packages. Understanding the dependency chain is critical for development:
+IGNIS is a monorepo with interdependent packages. Understanding the dependency chain is critical for development:
 
 ```
 dev-configs → inversion → helpers → boot → core
@@ -97,7 +97,7 @@ make update-boot
 make update-helpers
 make update-inversion
 make update-dev-configs
-make update-docs
+make update-docs-mcp
 ```
 
 ## 2. Development Workflow
@@ -107,8 +107,8 @@ make update-docs
 ```bash
 # Sync with upstream
 git fetch upstream
-git checkout main
-git merge upstream/main
+git checkout develop
+git merge upstream/develop
 
 # Create feature branch
 git checkout -b feature/your-feature-name
@@ -128,7 +128,7 @@ git checkout -b feature/your-feature-name
 - Follow [Code Style Standards](./code-style-standards/)
 - Follow [Architectural Patterns](./architectural-patterns.md)
 - Add tests for new features/fixes
-- Update docs in `packages/docs/wiki` if needed
+- Update docs in `docs/wiki/content/` if needed
 
 ### Step 3: Commit
 
@@ -155,14 +155,13 @@ git commit -m "chore: upgrade Hono to v4.0"
 ```bash
 # Lint and format (from root)
 make lint
-# Or: bun run lint:fix
+# Or run `bun run lint:fix` inside a package directory
 
-# Build all packages
+# Build all packages (from root)
 make build
-# Or: bun run build
 
-# Run tests
-bun run test
+# Run tests (from a package directory, e.g. packages/core or packages/boot)
+cd packages/core && bun test
 ```
 
 ## 3. Submit Pull Request
@@ -187,7 +186,7 @@ git push origin feature/your-feature-name
 - Code is linted and formatted
 - Documentation updated
 - Commit messages follow conventions
-- Branch is up-to-date with `main`
+- Branch is up-to-date with `develop`
 
 ## 4. Review Process
 
@@ -195,7 +194,7 @@ git push origin feature/your-feature-name
 1. Maintainer reviews your PR (usually within 2-3 days)
 2. Feedback or change requests may be provided
 3. Address feedback and push updates
-4. Once approved, maintainer merges to `main`
+4. Once approved, maintainer merges to `develop`
 
 **Responding to feedback:**
 ```bash
@@ -205,4 +204,4 @@ git commit -m "fix: address review feedback"
 git push origin feature/your-feature-name
 ```
 
-**Thank you for contributing to Ignis!**
+**Thank you for contributing to IGNIS!**