codeninja 2.0.0 → 3.1.0

package/ide/cursor/.cursor/rules/03-api-builder.mdc

@@ -0,0 +1,74 @@
+---
+description: codeninja API builder standards — loaded for NodeJS service files
+globs: ["**/modules/**", "**/middleware/**", "**/utilities/**", "**/route_manager*", "**/app.js", "**/languages/**"]
+alwaysApply: false
+---
+
+# codeninja — API Builder
+
+## 2-Layer Architecture (enforced)
+
+```
+modules/v1/<ModuleName>/
+├── route.js          ← HTTP only: validation, middleware, res.json()
+└── <module>_model.js ← DB only: parameterized queries, business logic
+```
+
+Never SQL in `route.js`. Never `res.json()` in `_model.js`.
+
+## 5-Step SOP — Every New Endpoint
+
+1. **ROUTING** — append to `route_manager.js` via `file_insert_after` (never rewrite)
+2. **VALIDATION** — validatorjs schema in `route.js`, match existing patterns
+3. **CONTROLLER** — model call + try/catch + `sendResponse()` in `route.js`
+4. **MODEL** — parameterized `$1,$2` SQL via pg pool in `_model.js`
+5. **LOCALIZE** — all strings in `languages/en.js`, use `file_contains` before adding
+
+## Middleware Chain Order (never change)
+```
+Language extraction → API key validation → JWT auth (protected only) → Rate limiting → Validation → Handler
+```
+
+## Response Contract
+```javascript
+{ status: 1, message: lang.key, data: result }   // success
+{ status: 0, message: lang.key }                  // error
+{ status: -1, message: lang.key }                 // session expired → triggers frontend logout
+```
+Always use `sendResponse(req, res, status, message, data)` from `utilities/response.js`.
+Never call `res.json()` directly.
+
+## Localizify Rules
+Only `headerValidator.js` and `response.js` may call `t()` or import localizify.
+All other files use `sendResponse()`, `getMessage()`, or `req.t("key")`.
+Never call `setLocale` from model files — race condition under concurrent requests.
+
+## Swagger Maintenance
+Patch `swagger_doc.json` only — never rewrite it.
+Add new path key only via `file_insert_after`. Update `info.version` timestamp.
+
+## JSDoc Standard (every exported function — no exceptions)
+```javascript
+/**
+ * One-sentence description. Active voice.
+ * @param {type} name - Description.
+ * @returns {Promise<Object>} Description.
+ */
+```
+Middleware: `@middleware` tag, no `@returns`.
+Route comment: `// POST /path — Business purpose.` above route definition.
+No inline `//` inside function bodies. No file-level headers.
+
+## Encryption Selection
+| context.services[n].client_type | Library | Demo file |
+|---------------------------------|---------|-----------|
+| reactjs | crypto-js AES-256-CBC | enc_dec.html |
+| app | cryptlib AES-256-CBC | enc_dec.php |
+
+`encrypted_transport: true` → encrypt full response payload.
+`encrypted_transport: false` → plain JSON, no transport encryption.
+KEY and IV always from context — never hardcode.
+
+## Test Standards (Jest + Supertest)
+File: `tests/v1/<ModuleName>.test.js`
+Cover: happy path, each validation failure, auth failure, edge cases.

package/ide/cursor/.cursor/rules/04-database.mdc

@@ -0,0 +1,87 @@
+---
+description: codeninja database standards — loaded for SQL migration files and database work
+globs: ["**/database/**", "**/*.sql", "**/migrations/**"]
+alwaysApply: false
+---
+
+# codeninja — Database Architect
+
+## Before Any SQL Generation
+Call `migration_next_number` MCP tool. NEVER invent table or column names.
+Load `context.db` fully. `database/` folder ALWAYS at repository root.
+
+## Naming (strict — no exceptions)
+| Element | Rule | Example |
+|---------|------|---------|
+| Table | `tbl_` prefix, lowercase, plural | `tbl_users` |
+| Column | lowercase snake_case | `user_id`, `created_at` |
+| PK | `id` bigint identity, first | always |
+| FK | `<table_singular_no_prefix>_id` | `user_id` → `tbl_users` |
+| Index (per-table) | `idx_<table_no_prefix>_<cols>` | `idx_users_email` |
+| Index (global) | `idx_tbl_<table>_<cols>` | `idx_tbl_users_email_is_deleted` |
+| Create file | `<N>-setup-tbl-<n>.sql` | `3-setup-tbl-users.sql` |
+| Alter file | `<N>-alter-tbl-<n>-<desc>.sql` | `12-alter-tbl-users-add-kyc.sql` |
+| Drop file | `<N>-drop-tbl-<n>.sql` | `13-drop-tbl-sessions.sql` |
+| Shared indexes | `111-setup-database-indexes.sql` | always last |
+
+## Primary Key (exact format)
+```sql
+id bigint NOT NULL GENERATED ALWAYS AS IDENTITY (INCREMENT 1 START 1 MINVALUE 1 MAXVALUE 9223372036854775807 CACHE 1),
+```
+`PRIMARY KEY (id)` at END of column block — never inline.
+
+## Column Types
+| Use | Type |
+|-----|------|
+| FK | `BIGINT NOT NULL DEFAULT 0` |
+| Names | `VARCHAR(64)`–`VARCHAR(255)` |
+| Short codes | `VARCHAR(8)`–`VARCHAR(32)` |
+| Email | `VARCHAR(132)` |
+| Token/password | `TEXT` |
+| Timestamp | `TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP` |
+| Status flag | `INTEGER NOT NULL DEFAULT 0 CHECK (status IN (0, 1))` |
+| Soft delete | `BOOLEAN NOT NULL DEFAULT FALSE` |
+| Price | `NUMERIC(18,8) NOT NULL DEFAULT 0.00000000` |
+| JSON | `JSON NOT NULL DEFAULT '{}'` |
+
+NEVER use PostgreSQL ENUM — always `VARCHAR + CHECK constraint`.
+Apply `NOT NULL` to every column by default.
+
+## SQL File Content Order (strict)
+```
+1. -- Comment: Creating <table> for <purpose>
+2. DROP TABLE IF EXISTS public.<table> CASCADE;
+3. CREATE TABLE block (id first, timestamps last)
+4. COMMENT ON COLUMN for every enum/flag column
+5. Per-table CREATE INDEX statements
+6. ALTER TABLE public.<table> OWNER TO <context.db.user>;
+7. GRANT ALL ON TABLE public.<table> TO <context.db.user>;
+8. INSERT seed data (reference tables only)
+```
+
+## Required Columns
+| Column | Every table | Entity tables | Log tables |
+|--------|------------|---------------|------------|
+| `id` | ✓ | ✓ | ✓ |
+| `created_at` | ✓ | ✓ | ✓ |
+| `status` | — | ✓ | — |
+| `is_deleted` | — | ✓ | — |
+
+## Index Rules — Always Index
+- Every FK column
+- `(status, is_deleted)` compound on entity tables
+- `created_at DESC` on log/event tables
+- `email` compound with `is_deleted` on user tables
+- Any WHERE or ORDER BY column in business queries
+
+## create-schema.sql
+Lives at `<repo_root>/database/<db_type>/create-schema.sql`. Auto-generated, never hand-edited.
+After every table operation: update `\i` entries in numeric order.
+`111-setup-database-indexes.sql` always last.
+
+## Permissions (end of every file)
+```sql
+ALTER TABLE public.<table> OWNER TO <context.db.user>;
+GRANT ALL ON TABLE public.<table> TO <context.db.user>;
+```
+Always from `context.db.user` — never hardcode username.

package/ide/cursor/.cursor/rules/05-reactjs.mdc

@@ -0,0 +1,83 @@
+---
+description: codeninja ReactJS standards — loaded for React app files
+globs: ["**/src/**", "**/public/**", "**/*.jsx", "**/*.css", "**/apiClient*", "**/apiHandler*"]
+alwaysApply: false
+---
+
+# codeninja — ReactJS Frontend
+
+## Backend Linking (enforced before any generation)
+```
+context.current_init.linked_service → backend service name
+context.services[linked].port       → REACT_APP_BASE_URL
+context.services[linked].encryption_key → REACT_APP_KEY
+context.services[linked].encryption_iv  → REACT_APP_IV
+context.services[linked].api_key        → REACT_APP_API_KEY
+```
+These 4 values are ALWAYS inherited. NEVER ask the user. NEVER hardcode.
+
+## File Structure
+```
+<service>/
+  public/
+    assets/css/style.css   ← global styles
+    index.html             ← single HTML shell
+    .htaccess              ← Apache SPA rewrite
+  src/
+    api/
+      apiClient.js         ← Axios + encrypt/decrypt interceptors
+      apiHandler.js        ← one export per API endpoint
+    components/            ← shared reusable components
+    pages/Welcome/
+      index.jsx
+      Welcome.module.css
+    App.jsx                ← React Router root
+    index.jsx              ← ReactDOM.createRoot
+  .env                     ← gitignored
+  .env.example             ← committed, values blank
+```
+
+## apiClient.js — 4 Responsibilities
+1. Static headers: `api-key`, `Accept-Language`, `Content-Type: text/plain`
+2. Request: encrypt body via AES-256-CBC; attach encrypted `token` from `localStorage('wa_token')` if present
+3. Response success: decrypt body; parse JSON; if `status === -1` → `logOutRedirectCall()`; if decrypt fails → return raw
+4. Response error: `ERR_NETWORK` or `401` → `logOutRedirectCall()` + `showErrorMessage()`
+
+KEY/IV: `CryptoJS.enc.Hex.parse(process.env.REACT_APP_KEY/IV)`.
+`logOutRedirectCall` and `showErrorMessage` imported from `../pages/common/Utils`.
+
+## apiHandler.js — Pattern
+```javascript
+export const functionName = async (data) => {
+  const res = await axiosClient.post('/path', data);
+  return res.data;
+};
+```
+- One async function per endpoint — no try/catch, no decryption
+- Session saving in handler, not in UI components
+- Functions match routes in `context.api_routes` for linked service
+
+## Code Style
+- Functional components only — no class components
+- JSDoc above every exported function and component
+- No inline styles — `.module.css` per page, `global.css` shared
+- No `console.log` — use `showMessage` / `showErrorMessage`
+- No hardcoded API paths — all calls through `apiHandler.js`
+
+## .env Contents
+```
+REACT_APP_BASE_URL=http://localhost:<linked_port>/api/v1/
+REACT_APP_API_KEY=<inherited>
+REACT_APP_KEY=<inherited>
+REACT_APP_IV=<inherited>
+```
+
+## @modularize
+Scan pages, find repeated layout blocks, extract to `src/components/<Name>/`.
+Rewrite pages to use component. Never change data-fetching or state.
+
+## @validate-page
+Client-side only. Per-field error messages below inputs. Preferred library from user.
+
+## @integrate-api
+Add handler in `apiHandler.js`. Wire buttons/forms. Add loading, error, success states.

package/ide/cursor/.cursor/rules/06-code-intelligence.mdc

@@ -0,0 +1,112 @@
+---
+description: codeninja code intelligence — loaded for explain, review, debug, optimize, audit commands
+globs: ["**/*"]
+alwaysApply: false
+---
+
+# codeninja — Code Intelligence
+
+All analysis commands use real project context — real file names, real column names,
+real service names from context.json. Never generic advice.
+
+## Before Any Analysis
+`context_read` → `fs_read` target → read 1–2 sibling files for pattern comparison.
+
+## /codeninja:explain
+```
+What it is     → 1–2 sentences, plain English
+How it works   → step-by-step key logic (skip boilerplate)
+Why this way   → architectural decision specific to this project
+Where connects → related files, functions, context entries
+```
+Use real names throughout. End: "Want me to explain further or show how to modify it?"
+
+## /codeninja:review — Checklist
+
+| Category | Level if failing | Checks |
+|----------|-----------------|--------|
+| Security | CRITICAL | POST/PUT/PATCH has validatorjs; apiKey middleware present; JWT on protected routes; no hardcoded secrets; parameterized SQL only; errors don't leak internals |
+| Architecture | WARNING | No SQL in route.js; no res.json() in _model.js; route_manager.js registered; swagger has entry; all strings in languages/en.js |
+| Code Quality | SUGGESTION | JSDoc on every function; no unused imports; no console.log; try/catch on async; no SELECT * |
+| Database | WARNING | Column names match context.db.schema; FK columns indexed; transactions on multi-write; LIMIT on unbounded queries |
+
+Output per finding:
+```
+[CRITICAL|WARNING|SUGGESTION]
+File:   path (~line N)
+Issue:  one-line description
+Before: current code
+After:  corrected code
+Why:    one sentence
+```
+End: `X critical · Y warnings · Z suggestions`
+Offer to apply. Confirm each before writing.
+
+## /codeninja:debug — Root Cause Process
+
+Gather: error + stack trace, endpoint, expected vs actual, recent changes.
+
+Request lifecycle trace order:
+```
+Language middleware → API key → JWT auth → Rate limit → Validation → Handler → Model → DB → Response
+```
+
+Common root causes:
+| Symptom | Check |
+|---------|-------|
+| `column does not exist` | context.db.schema vs code column names |
+| `undefined is not a function` | wrong import or missing export |
+| `Cannot read property` | missing null check after 0-row DB result |
+| `401 Unauthorized` | middleware order, header name spelling |
+| `500` | missing try/catch on async DB call |
+| Wrong row count | RANK vs DENSE_RANK, missing WHERE, missing dedup |
+| Migration not applied | table in code but not in DB — run migration |
+
+Fix output:
+```
+Root cause: [precise one sentence]
+File: path
+Before: [buggy code]
+After:  [fixed code]
+Why:    [one sentence]
+```
+Confirm before applying. Suggest one prevention guard after fix.
+
+## /codeninja:optimize — Analysis Checks
+
+DB queries (cross-reference `context.db.schema.<table>.indexes`):
+- Missing index on WHERE/JOIN/ORDER BY column → `CREATE INDEX CONCURRENTLY`
+- `SELECT *` → explicit column list
+- N+1 loop → JOIN or IN clause
+- No `LIMIT` on list queries
+- `RANK()` on leaderboards → `DENSE_RANK()` (no gaps after ties)
+- `DATE(col)` in WHERE → range filter (preserves index use)
+- Duplicate rows → `MIN(id) GROUP BY` dedup
+- Sort spilling to disk → `SET work_mem = '64MB'` session-level
+
+API routes:
+- Repeated DB calls → Redis cache suggestion
+- Missing pagination on list endpoints
+
+Output:
+```
+[HIGH|MED|LOW]
+Target:  what is slow
+Cause:   why it is slow
+Fix:     exact SQL or code
+Gain:    concrete estimate
+```
+For index additions: `migration_next_number` → generate `.sql` migration.
+`context_write` after applying index changes.
+
+## /codeninja:audit — Full Service
+
+Runs full review checklist PLUS:
+- `analyze_middleware_order` MCP tool
+- `analyze_encryption_library` MCP tool
+- `analyze_language_keys` MCP tool
+- `analyze_dependencies` MCP tool
+- `analyze_env_file` MCP tool
+- context.db.schema vs actual code column/table references
+
+Output: severity-ranked report by category. Auto-fix SUGGESTION. Confirm WARNING/CRITICAL.

package/ide/vscode/.github/copilot-instructions.md

@@ -0,0 +1,285 @@
+# codeninja — Project Intelligence for GitHub Copilot
+
+This file is auto-loaded by GitHub Copilot Agent Mode.
+It gives Copilot full awareness of this project's architecture, conventions,
+and all available slash commands.
+
+---
+
+## Section 1 — Global Orchestrator
+
+You are a Senior Software Architect managing this project via the codeninja system.
+
+### Activation Sequence (every session)
+1. Call `context_check_stale` — resolve stale operations first
+2. Call `context_read` — load full context
+3. Call `service_scan` — compare with `context.services`; suggest `/codeninja:sync` if drift
+4. Load `context.project_info` for all suggestions
+
+### Routing
+| Keyword trigger | Specialist domain |
+|----------------|------------------|
+| express, node, api, service, encryption | API Builder |
+| react, frontend, ui, component | ReactJS |
+| postgres, mysql, db, schema, migration, table | Database |
+| `/codeninja:db:*` | always Database |
+
+### Context Rules
+- NEVER read/write `context.json` directly — always `context_read` / `context_write`
+- `context_write` deep-merges — never overwrites the whole file
+- `change_log` is append-only
+
+### Batch Generation Rule
+ONE confirmation per operation. After user confirms → generate all files silently.
+No per-file prompts during `@init`, `@api`, or `@db:create`.
+
+### Response Style
+- One question at a time
+- Always confirm before creating or modifying files
+- `database/` folder ALWAYS at repository root — never inside a service folder
+- After scaffolding → always run task: `show-final-summary`
+
+---
+
+## Section 2 — MCP Tools and Context
+
+### Available MCP Tools
+| Tool | Purpose | When |
+|------|---------|------|
+| `context_read` | Load project context | FIRST on every activation |
+| `context_write` | Persist changes (deep-merge) | After every completed operation |
+| `context_clear_scratchpad` | Clear current_* key | After writing context |
+| `context_check_stale` | Detect unresolved scratchpad | Step 0 of activation |
+| `service_scan` | Discover all services on disk | Step 2 of activation |
+| `migration_next_number` | Next sequential migration number | Before any migration file |
+| `fs_read` | Read file from disk | Before modifying |
+| `fs_list` | List directory | When scanning structure |
+| `fs_exists` | Check existence | Before conditional ops |
+| `file_insert_after` | Surgical file insertion | route_manager.js, swagger |
+| `file_contains` | Check before appending | Avoid duplicates |
+| `run_drift_check` | Context vs disk | During @sync |
+| `lint_file` | Lint generated file | After JS/SQL generation |
+| `analyze_middleware_order` | Check middleware chain | During @audit |
+| `analyze_encryption_library` | Verify encryption | During @audit |
+| `analyze_language_keys` | Check i18n | During @audit |
+| `analyze_dependencies` | Scan package.json | During @audit |
+| `analyze_env_file` | Check .env completeness | During @audit |
+| `validate_redis_connection` | Test Redis | During init |
+| `validate_postgres_connection` | Test DB | During init |
+
+---
+
+## Section 3 — API Builder (NodeJS/Express)
+
+### 2-Layer Architecture (enforced)
+```
+modules/v1/<ModuleName>/
+├── route.js          ← HTTP only: validation, middleware, res.json()
+└── <module>_model.js ← DB only: queries, business logic
+```
+Never SQL in `route.js`. Never `res.json()` in `_model.js`.
+
+### 5-Step SOP for New Endpoints
+1. **ROUTING** — append to `route_manager.js` via `file_insert_after` (never rewrite)
+2. **VALIDATION** — validatorjs schema in `route.js`, match existing patterns
+3. **CONTROLLER** — model call + try/catch + `sendResponse()` in `route.js`
+4. **MODEL** — parameterized `$1,$2` SQL via pg pool in `_model.js`
+5. **LOCALIZE** — all strings in `languages/en.js`, check with `file_contains` first
+
+### Middleware Chain Order
+Language extraction → API key validation → JWT auth (protected only) → Rate limiting → Validation → Handler
+
+### Response Contract
+```javascript
+{ status: 1, message: lang.key, data: result }   // success
+{ status: 0, message: lang.key }                  // error
+{ status: -1, message: lang.key }                 // session expired
+```
+Always `sendResponse(req, res, status, message, data)`. Never `res.json()` directly.
+
+### Localizify Rules
+Only `headerValidator.js` and `response.js` may import localizify or call `t()`.
+All other files use `sendResponse()`, `getMessage()`, or `req.t("key")`.
+
+### Encryption Selection
+| client_type | Library | Demo file |
+|-------------|---------|-----------|
+| `reactjs` | crypto-js AES-256-CBC | enc_dec.html |
+| `app` | cryptlib AES-256-CBC | enc_dec.php |
+`encrypted_transport: true` → encrypt full response payload.
+KEY/IV always from context — never hardcode.
+
+### Service File Structure
+```
+<service>/
+  app.js, .env, .env.example, .gitignore, README.md, package.json
+  config/   common.js, constants.js, database.js, template.js
+  languages/   <lang>.js (one per supported_languages[])
+  logger/   logging.js, logs/ (gitignored)
+  middleware/   headerValidator.js, rateLimiter.js
+  modules/v1/   route_manager.js, <ModuleName>/route.js + <m>_model.js
+  utilities/   encryption.js, response.js, validator.js, ioRedis.js, notification.js
+  document/v1/   swagger_doc.json
+  tests/v1/   <ModuleName>.test.js
+  pem/ (gitignored), images/ (gitignored)
+```
+
+### JSDoc Standard
+```javascript
+/**
+ * One-sentence description. Active voice.
+ * @param {type} name - Description.
+ * @returns {Promise<Object>} Description.
+ */
+```
+Middleware: `@middleware` tag, no `@returns`. Route: `// POST /path — Business purpose.`
+No inline `//` inside function bodies. No file-level headers.
+
+---
+
+## Section 4 — Database Architect
+
+### Before Any SQL File
+Call `migration_next_number`. Load `context.db` fully. `database/` always at repo root.
+
+### Naming Conventions (strict)
+| Element | Rule | Example |
+|---------|------|---------|
+| Table | `tbl_` prefix, lowercase, plural | `tbl_users` |
+| Column | lowercase snake_case | `user_id`, `created_at` |
+| PK | `id` bigint identity, first column | always |
+| FK | `<table_singular_no_prefix>_id` | `user_id` refs `tbl_users` |
+| Create file | `<N>-setup-tbl-<n>.sql` | `3-setup-tbl-users.sql` |
+| Alter file | `<N>-alter-tbl-<n>-<desc>.sql` | `12-alter-tbl-users-add-kyc.sql` |
+| Drop file | `<N>-drop-tbl-<n>.sql` | `13-drop-tbl-sessions.sql` |
+| Shared indexes | `111-setup-database-indexes.sql` | always last |
+
+### Primary Key (exact)
+```sql
+id bigint NOT NULL GENERATED ALWAYS AS IDENTITY (INCREMENT 1 START 1 MINVALUE 1 MAXVALUE 9223372036854775807 CACHE 1),
+```
+`PRIMARY KEY (id)` at END of column block — never inline.
+
+### Column Types
+`BIGINT NOT NULL DEFAULT 0` (FK) · `VARCHAR(132)` (email) · `TEXT` (token/password)
+`TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP` · `BOOLEAN NOT NULL DEFAULT FALSE`
+`INTEGER NOT NULL DEFAULT 0 CHECK (status IN (0,1))` · `NUMERIC(18,8)` (financial)
+`JSON NOT NULL DEFAULT '{}'` · NEVER PostgreSQL ENUM — always `VARCHAR + CHECK`
+
+### SQL File Content Order
+```
+1. Comment header
+2. DROP TABLE IF EXISTS CASCADE
+3. CREATE TABLE (id first, timestamps last)
+4. COMMENT ON COLUMN (every enum/flag)
+5. Per-table CREATE INDEX
+6. ALTER TABLE OWNER TO <context.db.user>
+7. GRANT ALL ON TABLE TO <context.db.user>
+8. INSERT seed (reference tables only)
+```
+
+### Required Columns
+`id` + `created_at` on every table. `status` + `is_deleted` on entity tables. NOT on log/pivot tables.
+
+### Index Rules
+Always index: every FK, `(status,is_deleted)` compound, `created_at DESC` on logs, `email+is_deleted` compound on users, any WHERE/ORDER BY column.
+
+### create-schema.sql
+At `<repo_root>/database/<db_type>/create-schema.sql`. Auto-generated. `\i` entries in numeric order. `111-setup-database-indexes.sql` always last. Update after every table operation.
+
+---
+
+## Section 5 — ReactJS Frontend
+
+### Backend Linking (enforced)
+Inherit from `context.services[linked]`: `port` → `REACT_APP_BASE_URL`, `encryption_key` → `REACT_APP_KEY`, `encryption_iv` → `REACT_APP_IV`, `api_key` → `REACT_APP_API_KEY`.
+NEVER ask user for these. NEVER hardcode.
+
+### File Structure
+```
+<service>/public/assets/css/style.css  index.html  .htaccess
+src/api/apiClient.js  apiHandler.js
+src/components/  src/pages/Welcome/index.jsx  App.jsx  index.jsx
+.env (gitignored)  .env.example  package.json
+```
+
+### apiClient.js — 4 Responsibilities
+1. Static headers: `api-key`, `Accept-Language`, `Content-Type: text/plain`
+2. Request: encrypt body; attach encrypted `token` from `localStorage('wa_token')`
+3. Response success: decrypt; parse JSON; `status === -1` → logout
+4. Response error: `ERR_NETWORK` or `401` → logout + error message
+
+KEY/IV via `CryptoJS.enc.Hex.parse(process.env.REACT_APP_KEY/IV)`.
+
+### apiHandler.js
+One async function per endpoint. No try/catch, no decryption. Session saving in handler.
+
+### Code Style
+Functional components only. JSDoc on every export. `.module.css` per page. No `console.log`. No hardcoded API paths.
+
+---
+
+## Section 6 — Code Intelligence
+
+### /codeninja:explain
+What it is → How it works → Why this way → Where it connects.
+Use real names from context throughout.
+
+### /codeninja:review
+CRITICAL (security): missing validation, missing apiKey middleware, hardcoded secrets, string SQL concatenation.
+WARNING (architecture): SQL in route.js, res.json() in model.js, strings hardcoded.
+SUGGESTION (quality): missing JSDoc, console.log, SELECT *.
+Output: `[LEVEL] File: path  Issue/Before/After/Why`
+
+### /codeninja:debug
+Trace: Language → API key → JWT → Rate limit → Validation → Handler → Model → DB → Response.
+Check: column names vs context.db.schema, middleware order, missing try/catch, RANK vs DENSE_RANK.
+Output: root cause + before/after fix. Confirm before applying.
+
+### /codeninja:optimize
+DB: missing indexes (vs context.db.schema), SELECT *, N+1, no LIMIT, RANK() gaps, DATE() in WHERE, duplicate rows.
+Output: `[HIGH|MED|LOW]` Target/Cause/Fix/Gain. Generate migration for new indexes.
+
+### /codeninja:audit
+Full review + `analyze_middleware_order`, `analyze_encryption_library`, `analyze_language_keys`, `analyze_dependencies`, `analyze_env_file` MCP tools.
+
+---
+
+## Slash Commands Quick Reference
+
+Use with `@workspace` in Copilot Chat:
+
+| Command | Description |
+|---------|-------------|
+| `@workspace /codeninja:init` | Bootstrap NodeJS service, ReactJS app, or database |
+| `@workspace /codeninja:api` | Add API endpoint (5-step SOP) |
+| `@workspace /codeninja:design` | Plan feature before coding |
+| `@workspace /codeninja:audit` | Security and quality review |
+| `@workspace /codeninja:test` | Generate Jest tests |
+| `@workspace /codeninja:refactor` | Rename with context tracking |
+| `@workspace /codeninja:sync` | Rebuild context from repo |
+| `@workspace /codeninja:explain` | Explain any file or pattern |
+| `@workspace /codeninja:review` | Code review with findings |
+| `@workspace /codeninja:debug` | Debug with code path trace |
+| `@workspace /codeninja:optimize` | Performance improvements |
+| `@workspace /codeninja:db:create` | New table + migration |
+| `@workspace /codeninja:db:modify` | Alter column |
+| `@workspace /codeninja:db:index` | Add index |
+| `@workspace /codeninja:db:drop` | Drop table |
+| `@workspace /codeninja:db:seed` | Add seed data |
+| `@workspace /codeninja:db:sync` | Rebuild DB schema |
+| `@workspace @modularize` | Extract React layout components |
+| `@workspace @validate-page` | Add form validation |
+| `@workspace @integrate-api` | Wire forms to API handlers |
+
+---
+
+## File Locations
+
+| What | Path |
+|------|------|
+| Agent personas | `.codeninja/agent/` |
+| Workflow files | `.codeninja/commands/` |
+| Task files | `.codeninja/tasks/` |
+| Context | `.codeninja/context/context.json` |
+| MCP server | `.codeninja/mcp-server.js` |

package/ide/vscode/.vscode/mcp.json

@@ -0,0 +1,9 @@
+{
+  "servers": {
+    "codeninja": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${workspaceFolder}/.codeninja/mcp-server.js"]
+    }
+  }
+}