@cdmbase/wiki-browser 12.0.18-alpha.30 → 12.0.18-alpha.32

package/lib/templates/content/content-manifest.json

@@ -1,5 +1,17 @@
 {
   "files": [
+    {
+      "contentId": "botinstruction-zep_neo4j_knowledge_graph_guide",
+      "slug": "zep_neo4j_knowledge_graph_guide",
+      "filePath": "/content/docs/BotInstruction/ZEP_NEO4J_KNOWLEDGE_GRAPH_GUIDE.md",
+      "relativePath": "BotInstruction/ZEP_NEO4J_KNOWLEDGE_GRAPH_GUIDE.md",
+      "categoryId": "BotInstruction",
+      "title": "ZEP_NEO4J_KNOWLEDGE_GRAPH_GUIDE",
+      "description": "",
+      "author": "Documentation",
+      "updatedAt": "Recently",
+      "frontmatter": {}
+    },
     {
       "contentId": "generators-project-generate-fullproject",
       "slug": "project-generate-fullproject",
@@ -33,6 +45,18 @@
       "updatedAt": "Recently",
       "frontmatter": {}
     },
+    {
+      "contentId": "llm-templates_folder_and_codegen_guide",
+      "slug": "templates_folder_and_codegen_guide",
+      "filePath": "/content/docs/LLM/TEMPLATES_FOLDER_AND_CODEGEN_GUIDE.md",
+      "relativePath": "LLM/TEMPLATES_FOLDER_AND_CODEGEN_GUIDE.md",
+      "categoryId": "LLM",
+      "title": "TEMPLATES_FOLDER_AND_CODEGEN_GUIDE",
+      "description": "",
+      "author": "Documentation",
+      "updatedAt": "Recently",
+      "frontmatter": {}
+    },
     {
       "contentId": "llm-backend-proxies-services-llm",
       "slug": "backend-proxies-services-llm",
@@ -3533,6 +3557,23 @@
     }
   ],
   "categories": {
+    "BotInstruction": {
+      "id": "BotInstruction",
+      "title": "BotInstruction",
+      "description": "BotInstruction Documentation",
+      "iconType": "Documentation",
+      "articles": [
+        {
+          "id": "botinstruction-zep_neo4j_knowledge_graph_guide",
+          "title": "ZEP_NEO4J_KNOWLEDGE_GRAPH_GUIDE",
+          "description": "",
+          "slug": "zep_neo4j_knowledge_graph_guide",
+          "author": "Documentation",
+          "updatedAt": "Recently",
+          "categoryId": "BotInstruction"
+        }
+      ]
+    },
     "Generators": {
       "id": "Generators",
       "title": "Generators",
@@ -3681,6 +3722,15 @@
           "author": "Documentation",
           "updatedAt": "Recently",
           "categoryId": "LLM"
+        },
+        {
+          "id": "llm-templates_folder_and_codegen_guide",
+          "title": "TEMPLATES_FOLDER_AND_CODEGEN_GUIDE",
+          "description": "",
+          "slug": "templates_folder_and_codegen_guide",
+          "author": "Documentation",
+          "updatedAt": "Recently",
+          "categoryId": "LLM"
         }
       ]
     },
@@ -5359,8 +5409,10 @@
     }
   },
   "contentPathMap": {
+    "botinstruction-zep_neo4j_knowledge_graph_guide": "/content/docs/BotInstruction/ZEP_NEO4J_KNOWLEDGE_GRAPH_GUIDE.md",
     "generators-project-generate-fullproject": "/content/docs/Generators/Project/generate-fullproject.md",
     "llm-logger.llm": "/content/docs/LLM/Logger.llm.md",
+    "llm-templates_folder_and_codegen_guide": "/content/docs/LLM/TEMPLATES_FOLDER_AND_CODEGEN_GUIDE.md",
     "llm-backend-proxies-services-llm": "/content/docs/LLM/backend-proxies-services-llm.md",
     "llm-backend-service-llm": "/content/docs/LLM/backend-service-llm.md",
     "llm-db_migration_llm": "/content/docs/LLM/db_migration_llm.md",
@@ -6304,6 +6356,28 @@
           }
         ]
       },
+      {
+        "type": "directory",
+        "name": "BotInstruction",
+        "path": "BotInstruction",
+        "children": [
+          {
+            "type": "file",
+            "name": "ZEP_NEO4J_KNOWLEDGE_GRAPH_GUIDE",
+            "title": "ZEP_NEO4J_KNOWLEDGE_GRAPH_GUIDE",
+            "path": "BotInstruction/ZEP_NEO4J_KNOWLEDGE_GRAPH_GUIDE.md",
+            "contentId": "botinstruction-zep_neo4j_knowledge_graph_guide",
+            "slug": "zep_neo4j_knowledge_graph_guide",
+            "categoryId": "BotInstruction",
+            "filePath": "/content/docs/BotInstruction/ZEP_NEO4J_KNOWLEDGE_GRAPH_GUIDE.md",
+            "relativePath": "BotInstruction/ZEP_NEO4J_KNOWLEDGE_GRAPH_GUIDE.md",
+            "description": "",
+            "author": "Documentation",
+            "updatedAt": "Recently",
+            "frontmatter": {}
+          }
+        ]
+      },
       {
         "type": "directory",
         "name": "chrome-extension",
@@ -8519,6 +8593,21 @@
             "author": "Documentation",
             "updatedAt": "Recently",
             "frontmatter": {}
+          },
+          {
+            "type": "file",
+            "name": "TEMPLATES_FOLDER_AND_CODEGEN_GUIDE",
+            "title": "TEMPLATES_FOLDER_AND_CODEGEN_GUIDE",
+            "path": "LLM/TEMPLATES_FOLDER_AND_CODEGEN_GUIDE.md",
+            "contentId": "llm-templates_folder_and_codegen_guide",
+            "slug": "templates_folder_and_codegen_guide",
+            "categoryId": "LLM",
+            "filePath": "/content/docs/LLM/TEMPLATES_FOLDER_AND_CODEGEN_GUIDE.md",
+            "relativePath": "LLM/TEMPLATES_FOLDER_AND_CODEGEN_GUIDE.md",
+            "description": "",
+            "author": "Documentation",
+            "updatedAt": "Recently",
+            "frontmatter": {}
           }
         ]
       },
@@ -10294,6 +10383,19 @@
       ],
       "isFile": false
     },
+    {
+      "title": "BotInstruction",
+      "path": null,
+      "children": [
+        {
+          "title": "ZEP_NEO4J_KNOWLEDGE_GRAPH_GUIDE",
+          "path": "/help/BotInstruction/zep_neo4j_knowledge_graph_guide",
+          "children": [],
+          "isFile": true
+        }
+      ],
+      "isFile": false
+    },
     {
       "title": "Chrome Extension",
       "path": null,
@@ -10996,6 +11098,12 @@
           "path": "/help/LLM/tailwind-css-llm",
           "children": [],
           "isFile": true
+        },
+        {
+          "title": "TEMPLATES_FOLDER_AND_CODEGEN_GUIDE",
+          "path": "/help/LLM/templates_folder_and_codegen_guide",
+          "children": [],
+          "isFile": true
         }
       ],
       "isFile": false

package/lib/templates/content/docs/BotInstruction/ZEP_NEO4J_KNOWLEDGE_GRAPH_GUIDE.md

@@ -0,0 +1,217 @@
+# Zep + Neo4j Knowledge Graph Guide for LLM Agents
+
+## Overview
+
+This guide documents how to use Zep CE (Community Edition) backed by Neo4j as a knowledge graph for LLM-assisted development. It enables semantic search across all CDEBase documentation, auto-extraction of entities and relationships, and a self-improving knowledge loop.
+
+## Architecture
+
+```
+LLM Agent → Zep CE API (store messages) → Neo4j (entities, relationships, embeddings)
+                                          ↗
+LLM Agent → Neo4j HTTP API (direct queries, graph traversal)
+                                          ↗
+LLM Agent → Zep Search API (semantic fact search)
+```
+
+## Configuration
+
+### Zep API
+- **URL**: `https://zep.cdebase.dev`
+- **Auth Header**: `Authorization: Api-Key <your-api-key>`
+- **Message limit**: 2500 chars per message (chunk larger content at 2400 chars)
+
+### Neo4j (Zep Backend)
+- **HTTP API**: `https://neo4j.cdebase.dev/db/neo4j/tx/commit`
+- **Bolt**: `neo4j-bolt.cdebase.dev:443`
+- **Auth**: Basic auth (username/password)
+
+### Zep Sessions
+- `cdebase-llm-guides` — All CDEBase wiki docs (LLM guides, adminide-modules, remix, feature-api, etc.)
+- Create additional sessions per project or user as needed
+
+## Semantic Search
+
+The most powerful feature — search across all stored knowledge by meaning, not just keywords.
+
+### Search Endpoint
+```bash
+curl -s -X POST "https://zep.cdebase.dev/api/v2/sessions/search" \
+  -H "Authorization: Api-Key <your-api-key>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "DataLoader implementation pattern",
+    "session_ids": ["cdebase-llm-guides"],
+    "limit": 10
+  }'
+```
+
+**CRITICAL**: The search endpoint is **top-level** (`/api/v2/sessions/search`), NOT per-session (`/sessions/{id}/search`). The `session_ids` array in the request body filters results.
+
+### Search Returns Facts
+Zep automatically extracts **facts** from stored messages. Search returns these facts ranked by semantic similarity:
+
+```json
+{
+  "results": [
+    {
+      "fact": {
+        "uuid": "...",
+        "fact": "DataLoader Pattern ensures Consistency by resolving all object references through the same pattern.",
+        "created_at": "2026-02-17T01:06:03Z"
+      }
+    }
+  ]
+}
+```
+
+## Storing Content
+
+### Add Messages to Zep
+```bash
+curl -s -X POST "https://zep.cdebase.dev/api/v2/sessions/<session_id>/memory" \
+  -H "Authorization: Api-Key <your-api-key>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [
+      {"role": "user", "role_type": "user", "content": "Topic label"},
+      {"role": "assistant", "role_type": "assistant", "content": "Actual content here (max 2500 chars)"}
+    ]
+  }'
+```
+
+### Chunking Large Documents
+For documents > 2500 chars, split into chunks:
+
+```python
+import json, math, urllib.request
+
+ZEP_URL = "https://zep.cdebase.dev"
+ZEP_KEY = "your-api-key"
+MAX_CHARS = 2400  # Under 2500 limit
+
+def push_to_zep(session_id, name, content):
+    chunks = math.ceil(len(content) / MAX_CHARS)
+    for i in range(chunks):
+        chunk = content[i*MAX_CHARS:(i+1)*MAX_CHARS]
+        part = f" (part {i+1}/{chunks})" if chunks > 1 else ""
+        payload = {
+            "messages": [
+                {"role": "user", "role_type": "user", "content": f"{name}{part}"},
+                {"role": "assistant", "role_type": "assistant", "content": chunk}
+            ]
+        }
+        req = urllib.request.Request(
+            f"{ZEP_URL}/api/v2/sessions/{session_id}/memory",
+            data=json.dumps(payload).encode(),
+            headers={"Authorization": f"Api-Key {ZEP_KEY}", "Content-Type": "application/json"},
+            method="POST"
+        )
+        urllib.request.urlopen(req)
+```
+
+## Neo4j Direct Queries
+
+For graph traversal and raw text search, query Neo4j directly.
+
+### Query Template
+```bash
+curl -s -X POST "https://neo4j.cdebase.dev/db/neo4j/tx/commit" \
+  -H "Content-Type: application/json" \
+  -u "username:password" \
+  -d '{"statements": [{"statement": "YOUR CYPHER QUERY"}]}'
+```
+
+### Useful Queries
+
+**Graph stats:**
+```cypher
+MATCH (n:Entity) RETURN count(n) as entities
+```
+
+**List all entities:**
+```cypher
+MATCH (n:Entity) WHERE n.name <> 'User '
+RETURN DISTINCT n.name ORDER BY n.name
+```
+
+**Find relationships for a concept:**
+```cypher
+MATCH (n:Entity {name: 'GraphQL'})-[r]-(related)
+RETURN n.name, type(r), related.name LIMIT 20
+```
+
+**Text search across content:**
+```cypher
+MATCH (n) WHERE n.content CONTAINS 'createServiceFunc'
+RETURN substring(n.content, 0, 300) LIMIT 5
+```
+
+**Visual graph (use in Neo4j Browser):**
+```cypher
+MATCH (a:Entity)-[r]->(b:Entity)
+WHERE a.name <> 'User ' AND b.name <> 'User '
+RETURN a, r, b LIMIT 200
+```
+
+## Self-Improving Knowledge Loop
+
+When an LLM agent encounters missing or poor context:
+
+1. **Search Zep** → `POST /api/v2/sessions/search` with the topic
+2. **If poor results** → Query Neo4j raw for related content
+3. **Write new guide** → Create/update a `.md` file with the discovered patterns
+4. **Save locally** → Keep in workspace `references/` directory
+5. **Push to Zep** → Chunk and send to `cdebase-llm-guides` session
+6. **PR to wiki** → Branch from `develop`, add to `docs/LLM/` or appropriate folder, PR to `cdmbase/cdebase-wiki`
+
+This creates a feedback loop where the knowledge graph improves with every coding task.
+
+## Node Labels in Neo4j
+
+Zep CE creates these node types:
+- `Entity` — Extracted concepts (GraphQL, Mongoose, DataLoader, etc.)
+- `Episodic` — Individual message memories
+- `Community` — Clustered topic groups
+
+### Relationship Types
+- `RELATES_TO` — General relationship between entities
+- `MENTIONS` — Entity mentioned in an episodic memory
+- `HAS_MEMBER` — Community membership
+
+## MCP Server Integration
+
+A lightweight MCP server (`server.mjs`) exposes Zep to VS Code Copilot and other MCP clients:
+
+```json
+{
+  "mcpServers": {
+    "zep": {
+      "command": "node",
+      "args": ["server.mjs"],
+      "env": {
+        "ZEP_API_URL": "https://zep.cdebase.dev",
+        "ZEP_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### MCP Tools
+| Tool | Description |
+|------|-------------|
+| `search_memory` | Semantic search across session facts |
+| `get_session_messages` | Retrieve messages from a session |
+| `get_session_memory` | Get memory summary and context |
+| `list_sessions` | List all sessions |
+| `list_users` / `get_user` | User management |
+
+## Best Practices
+
+1. **Always search before coding** — Query Zep for patterns before writing code for any CDEBase project
+2. **Chunk at 2400 chars** — Stay under the 2500 char message limit
+3. **Use descriptive labels** — Name chunks clearly (e.g., "CDEBase LLM guide: backend-service (part 3/8)")
+4. **Dedicated sessions** — Use `cdebase-llm-guides` for docs, create separate sessions for project-specific context
+5. **Keep local copies** — Always save `.md` files locally before pushing to Zep
+6. **PR everything** — New guides must be PR'd to the wiki repo for persistence

package/lib/templates/content/docs/LLM/TEMPLATES_FOLDER_AND_CODEGEN_GUIDE.md

@@ -0,0 +1,392 @@
+# Templates Folder Pattern & Code Generation Pipeline
+
+## Overview
+
+The `packages/common/` package in both adminIde-stack and forms-stack is **entirely auto-generated**. You should **NEVER manually edit** files in `packages/common/`. Instead, all service interfaces, repository interfaces, SERVER_TYPES entries, and service-schemas are generated from **templates folders** inside each server module, combined with GraphQL schema codegen.
+
+## The Templates Folder Pattern
+
+### Location
+
+Every server module has a `templates/` folder at:
+
+```
+packages-modules/{module}/server/src/templates/
+```
+
+Or in forms-stack:
+
+```
+packages/{module}/server/src/templates/
+```
+
+### Structure
+
+```
+templates/
+├── constants/
+│   ├── SERVER_TYPES.ts.template     ← Symbol.for() DI tokens for this module
+│   ├── DB_COLL_NAMES.ts.template    ← MongoDB collection names
+│   └── DB_SLUG_NAMES.ts.template    ← (optional) slug name constants
+├── repositories/
+│   └── {EntityName}Repository.ts.template  ← Repository interface (I{EntityName}Repository)
+└── services/
+    ├── {EntityName}Service.ts.template     ← Service interface (I{EntityName}Service)
+    └── {EntityName}DataLoader.ts.template  ← DataLoader interface (optional)
+```
+
+### Template File Format
+
+Template files use `.ts.template` extension but are **plain TypeScript** — NOT Handlebars/EJS. They are authoritative source files that get **copied/merged** into `packages/common/src/` during the `regenerateGraphql` process.
+
+#### Example: SERVER_TYPES.ts.template
+
+```typescript
+// packages-modules/marketplace/server/src/templates/constants/SERVER_TYPES.ts.template
+export const SERVER_TYPES = {
+    IRegistryExtensionService: Symbol.for('IRegistryExtensionService'),
+    IRegistryExtensionRepository: Symbol.for('IRegistryExtensionRepository'),
+    IExtensionContributionService: Symbol.for('IExtensionContributionService'),
+    IExtensionContributesProvider: Symbol.for('IExtensionContributesProvider'),
+};
+```
+
+#### Example: Service Interface Template
+
+```typescript
+// packages-modules/marketplace/server/src/templates/services/ExtensionContributionService.ts.template
+import { IExtensionContributes } from 'common/server'; // ← reuse the generated GraphQL type
+
+export interface IExtensionContributesProvider {
+    getContributes(extensionId: string, version?: string): Promise<IExtensionContributes>;
+}
+
+export interface IExtensionContributionService {
+    registerProvider(sourceCollection: string, provider: IExtensionContributesProvider): void;
+    getContributions(extensionId: string, version?: string): Promise<IExtensionContributes | null>;
+}
+
+declare module '../apollo-context' {
+    interface ServerContext {
+        extensionContributionService: IExtensionContributionService;
+    }
+}
+```
+
+> **Preference: Reuse Generated GraphQL Types**
+>
+> When a type is already defined in the `.graphql` schema and gets generated as a TypeScript type in `generated-models.ts`, the template should **import and reuse** that generated type via `import { ITypeName } from 'common/server'` rather than redefining its own version. This avoids type duplication and keeps a single source of truth for the type shape.
+>
+> See [Reusing Generated GraphQL Types in Templates](#reusing-generated-graphql-types-in-templates) for details.
+
+### What Gets Generated Where
+
+| Template Source                                         | Generated Destination                                              |
+| ------------------------------------------------------- | ------------------------------------------------------------------ |
+| `templates/constants/SERVER_TYPES.ts.template`          | **MERGED** into `packages/common/src/constants/SERVER_TYPES.ts`    |
+| `templates/services/{Entity}Service.ts.template`        | **COPIED** to `packages/common/src/services/{Entity}Service.ts`    |
+| `templates/repositories/{Entity}Repository.ts.template` | **COPIED** to `packages/common/src/services/{Entity}Repository.ts` |
+| `templates/constants/DB_COLL_NAMES.ts.template`         | **MERGED** into `packages/common/src/constants/DB_COLL_NAMES.ts`   |
+| _(barrel exports)_                                      | `packages/common/src/services/index.ts` is **auto-updated**        |
+
+The merged SERVER_TYPES.ts has comments showing which module contributed each block:
+
+```typescript
+// from package: platform-server
+IAccountService: Symbol.for('IAccountService'),
+// from package: marketplace-module-server
+IRegistryExtensionService: Symbol.for('IRegistryExtensionService'),
+```
+
+## Code Generation Pipeline
+
+### Commands
+
+| Command                  | Script                                   | Purpose                                                    |
+| ------------------------ | ---------------------------------------- | ---------------------------------------------------------- |
+| `yarn regenerateGraphql` | `tools/codegenGenerator.mjs`             | Discover schemas + copy templates → generates `codegen.ts` |
+| `yarn generateGraphql`   | `graphql-codegen-esm` (reads codegen.ts) | Generate TypeScript types, Zod schemas, Apollo hooks       |
+| `postgenerateGraphql`    | `lerna run build --scope=common`         | Build the common package (auto-runs after generateGraphql) |
+
+### Step 1: `yarn regenerateGraphql`
+
+Runs `tools/codegenGenerator.mjs` which:
+
+1. Reads `cdecode-config.json` for configuration
+2. Calls `@common-stack/rollup-vite-utils` codegen utilities
+3. **Discovers** all `.graphql` / `.gql` schemas from:
+    - `node_modules/@adminide-stack/*/lib/**/*.graphql` (npm packages)
+    - `packages/*/server/src/**/*.graphql` (local packages)
+4. **Copies all templates/** to `packages/common/src/`:
+    - Merges all `SERVER_TYPES.ts.template` into one `SERVER_TYPES.ts`
+    - Copies service/repository interfaces to `services/`
+    - Updates `services/index.ts` barrel exports
+5. **Generates** `codegen.ts` with resolved schema paths
+
+### Step 2: `yarn generateGraphql`
+
+Runs `graphql-codegen-esm` which reads the generated `codegen.ts` and produces 4 output files in `packages/common/src/generated/`:
+
+| Output File                | Plugin                                                                      | Purpose                                         |
+| -------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------- |
+| `generated-models.ts`      | typescript, typescript-operations, typescript-resolvers, typescript-mongodb | TypeScript interfaces/types from GraphQL schema |
+| `generated-zod-schemas.ts` | `@common-stack/codegen-zod/graphql`                                         | Zod validation schemas from GraphQL types       |
+| `generated.tsx`            | typescript-react-apollo                                                     | React Apollo query/mutation hooks               |
+| `introspection-result.ts`  | fragment-matcher                                                            | Apollo cache fragment matching                  |
+
+After writing all files, two **afterAllFileWrite** hooks run:
+
+1. `node scripts/fix-enum-references.js` — Fixes enum reference issues in generated code
+2. `node node_modules/@common-stack/codegen-zod/dist/service/generateAllServiceSchemas.js` — Generates `service-schemas.ts`
+
+### Step 3: `generateAllServiceSchemas.js`
+
+This script (from `@common-stack/codegen-zod`):
+
+1. Reads `cdecode-config.json` → `serviceSchemas` section:
+    ```json
+    {
+        "serviceSchemas": {
+            "servicesDir": "packages/common/src/services",
+            "outputFile": "packages/common/src/generated/service-schemas.ts",
+            "skipServices": ["AuthBackendClient", "PubSub", ...],
+            "graphqlSchemasPath": "packages/common/src/generated/generated-zod-schemas.ts"
+        }
+    }
+    ```
+2. **Scans** `packages/common/src/services/` for all `.ts` files
+3. **Parses** each file with TypeScript compiler API looking for `export interface I*Service` or `I*Manager`
+4. **Extracts** method signatures (parameter names, types, optionality)
+5. **Cross-references** with `generated-zod-schemas.ts` to find Zod schemas for GraphQL types
+6. **Generates** `service-schemas.ts` with:
+    - A `{ServiceName}Schemas` object per service interface
+    - Zod schemas for each method's parameters
+    - A `topic` property (Moleculer service name)
+    - An aggregated `AllServiceSchemas` export
+
+### Step 4: `postgenerateGraphql`
+
+Automatically runs after `generateGraphql`:
+
+- `lerna run build --scope=common` — Compiles the common package so other packages can use the new types
+
+## Complete Pipeline Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  yarn regenerateGraphql                                          │
+│  └─ tools/codegenGenerator.mjs                                   │
+│     └─ reads cdecode-config.json                                 │
+│     └─ calls @common-stack/rollup-vite-utils/codegen             │
+│        ├─ Discovers .graphql/.gql schemas from node_modules +    │
+│        │  local packages                                          │
+│        ├─ Generates codegen.ts with resolved paths               │
+│        ├─ Copies all templates/ → packages/common/src/           │
+│        │  ├─ services/*.ts.template → services/*.ts              │
+│        │  ├─ constants/SERVER_TYPES.ts.template → MERGED into    │
+│        │  │   constants/SERVER_TYPES.ts                           │
+│        │  └─ Updates services/index.ts barrel exports            │
+│        └─ Sets up common package boilerplate                     │
+├─────────────────────────────────────────────────────────────────┤
+│  yarn generateGraphql                                            │
+│  └─ graphql-codegen-esm (reads codegen.ts)                       │
+│     └─ Generates 4 files in packages/common/src/generated/:     │
+│        ├─ generated-models.ts     (TS types from .graphql)       │
+│        ├─ generated-zod-schemas.ts (Zod schemas)                 │
+│        ├─ generated.tsx           (React Apollo hooks)           │
+│        └─ introspection-result.ts (fragment matcher)             │
+│     └─ afterAllFileWrite hooks:                                  │
+│        ├─ fix-enum-references.js                                 │
+│        └─ generateAllServiceSchemas.js                           │
+│           └─ Scans services/ interfaces → generates              │
+│              service-schemas.ts (Zod schemas for Moleculer)      │
+├─────────────────────────────────────────────────────────────────┤
+│  postgenerateGraphql (auto-runs)                                 │
+│  └─ lerna run build --scope=common                               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## How to Add a New Backend Service
+
+### Step 1: Create the GraphQL Schema
+
+Create a `.graphql` file in the server module:
+
+```
+packages-modules/{module}/server/src/graphql/schemas/{entity}.graphql
+```
+
+Define types, queries, mutations.
+
+### Step 2: Create Template Files
+
+Create template files in the server module's `templates/` folder:
+
+**SERVICE_TYPES entries:**
+
+```
+packages-modules/{module}/server/src/templates/constants/SERVER_TYPES.ts.template
+```
+
+Add Symbol.for() entries for new service/repository/dataloader.
+
+**Service interface:**
+
+```
+packages-modules/{module}/server/src/templates/services/{EntityName}Service.ts.template
+```
+
+Define the `I{EntityName}Service` interface with method signatures.
+
+**Repository interface (if needed):**
+
+```
+packages-modules/{module}/server/src/templates/repositories/{EntityName}Repository.ts.template
+```
+
+### Step 3: Run Code Generation
+
+```bash
+yarn regenerateGraphql   # Discovers schemas + copies templates to common
+yarn generateGraphql      # Generates TS types, Zod schemas, Apollo hooks, service-schemas
+```
+
+After this, `packages/common/` will have:
+
+- Updated `SERVER_TYPES.ts` with new symbols
+- New service interface file in `services/`
+- Updated `services/index.ts` barrel exports
+- Updated `generated-models.ts` with GraphQL types
+- Updated `service-schemas.ts` with Moleculer schemas
+
+### Step 4: Implement the Service
+
+Create the concrete implementation:
+
+```
+packages-modules/{module}/server/src/services/{entity-name}-service.ts
+```
+
+### Step 5: Create Container Module
+
+Bind the service in the container:
+
+```
+packages-modules/{module}/server/src/containers/module.ts
+```
+
+### Step 6: Create Resolver
+
+Create the GraphQL resolver:
+
+```
+packages-modules/{module}/server/src/graphql/resolvers/{entity-name}-resolver.ts
+```
+
+### Step 7: Wire into Feature Module
+
+Update the Feature in:
+
+```
+packages-modules/{module}/server/src/module.ts
+```
+
+## Reusing Generated GraphQL Types in Templates
+
+When writing `.ts.template` files, **always prefer importing types that are already generated from GraphQL schemas** rather than defining duplicate interfaces manually.
+
+### Why
+
+The `yarn generateGraphql` step produces TypeScript types in `packages/common/src/generated/generated-models.ts` for every GraphQL type, query, and mutation. These generated types are the **single source of truth** for the shape of data flowing through the GraphQL layer. If a template redefines the same structure (even with a different name), the two can drift apart when the schema evolves.
+
+### How
+
+Template files are copied into `packages/common/src/services/` — so they can import from `'common/server'` just like any other file in the common package. The generated types are re-exported through `common/server`.
+
+```typescript
+// ✅ CORRECT — import the generated type
+import { IExtensionContributes } from 'common/server';
+
+export interface IExtensionContributesProvider {
+    getContributes(extensionId: string, version?: string): Promise<IExtensionContributes>;
+}
+```
+
+```typescript
+// ❌ WRONG — manually redefining the same shape
+export interface IExtensionContributesResult {
+    uiLayout?: Record<string, unknown>[];
+    configuration?: Record<string, unknown>[];
+    // ... duplicates the GraphQL-generated IExtensionContributes
+}
+
+export interface IExtensionContributesProvider {
+    getContributes(extensionId: string, version?: string): Promise<IExtensionContributesResult>;
+}
+```
+
+### When to Define Your Own Types
+
+Only define a type locally in the template when:
+
+- The type has **no corresponding GraphQL schema definition** (e.g., an internal-only DTO not exposed via the API)
+- The type intentionally **differs** from the GraphQL type (e.g., a partial/extended variant)
+- The type is a **generic utility** interface not tied to a schema entity
+
+### Existing Templates That Import Generated Types
+
+Many existing templates already follow this pattern:
+
+| Template                                   | Imports from `'common/server'`                                                                        |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `ExtensionGalleryService.ts.template`      | `IGalleryExtension`, `IExtensionManifest`, `IGalleryPager`, `AsDomainType`, `IRegistryExtensionModel` |
+| `ExtensionGalleryDataLoader.ts.template`   | `IGalleryExtension`, `IDataLoader`                                                                    |
+| `InstalledExtensionService.ts.template`    | Multiple model types                                                                                  |
+| `MarketplacePublisherService.ts.template`  | `IMarketplacePublisherModel`, `AsDomainType`                                                          |
+| `ExtensionContributionService.ts.template` | `IExtensionContributes`                                                                               |
+
+### Pipeline Order Consideration
+
+Since `yarn regenerateGraphql` (copies templates) runs **before** `yarn generateGraphql` (generates types), you might wonder: how can a template import a type that hasn't been generated yet?
+
+The answer is that generated types from **previous runs** are already present in `packages/common/src/generated/`. The pipeline is designed to be run incrementally:
+
+1. First run: Define the `.graphql` schema → `generateGraphql` produces the types
+2. Second run (or same session): Create the template that imports those types → `regenerateGraphql` copies the template → `generateGraphql` regenerates (types already exist)
+
+In practice, you always run both commands together, so the generated types are available by the time the common package is compiled.
+
+## Key Rules
+
+1. **NEVER manually edit `packages/common/`** — all files are generated
+2. **ALWAYS create `.ts.template` files** in your module's `templates/` folder for new interfaces
+3. **ALWAYS run `yarn regenerateGraphql`** after creating/modifying template files
+4. **ALWAYS run `yarn generateGraphql`** after creating/modifying `.graphql` schema files
+5. **The `postgenerateGraphql` script runs automatically** — no need to manually build common
+6. **SERVER_TYPES.ts is a merge of ALL modules'** `SERVER_TYPES.ts.template` files
+7. **service-schemas.ts is auto-generated** from service interfaces in `packages/common/src/services/`
+8. **PREFER importing generated GraphQL types** (`import { ITypeName } from 'common/server'`) over redefining the same shape in templates — the GraphQL schema is the single source of truth for API types
+
+## Downstream Stacks (e.g., forms-stack)
+
+Downstream stacks consume upstream npm packages. The flow:
+
+1. Upstream (adminIde-stack) publishes `@adminide-stack/*` packages with compiled `.graphql` schemas in `lib/`
+2. Downstream `codegen.ts` picks up schemas from `node_modules/@adminide-stack/*/lib/**/*.graphql`
+3. Downstream `yarn regenerateGraphql` copies templates from both:
+    - npm packages (upstream templates)
+    - Local packages (downstream-only templates)
+4. This is why downstream common packages have upstream types — they come through the template copy process
+
+### Adding a New Service in Downstream Stack
+
+If the service interface already exists in the upstream npm package:
+
+- Just run `yarn regenerateGraphql` — it will copy the template from `node_modules/`
+- Then run `yarn generateGraphql` — it will pick up `.graphql` schemas from `node_modules/`
+
+If the upstream package hasn't been published yet:
+
+- Define interfaces **locally** in the module (NOT in common)
+- Use `Symbol.for()` for DI tokens to ensure cross-container compatibility
+- Once upstream publishes, run `yarn regenerateGraphql` to get the official templates

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cdmbase/wiki-browser",
-    "version": "12.0.18-alpha.30",
+    "version": "12.0.18-alpha.32",
     "description": "Sample core for higher packages to depend on",
     "license": "ISC",
     "author": "CDMBase LLC",
@@ -65,7 +65,7 @@
             }
         ]
     },
-    "gitHead": "28986d00b5780b627128c660f480f9bae81319ad",
+    "gitHead": "68d47d67cfcd0834d97daa5c81223473354bffd2",
     "typescript": {
         "definition": "lib/index.d.ts"
     }