Feature/125 c 001 design faq storage model

README.md

@@ -57,6 +57,7 @@ Planned features
 
 - 🤖 [Discord Bot Setup Guide](docs/discord-bot-setup.md)
 - 📘 [Command Reference](docs/commands.md)
+- ❓ [FAQ Storage Design](docs/faq.md)
 - 🧠 [Transcript & Summary Design](docs/transcripts.md)
 - 🛠️ [Development Notes](docs/dev-notes.md)
 
@@ -143,6 +144,7 @@ OmegaBot is online
 ├── docs
 │   ├── commands.md
 │   ├── dev-notes.md
+│   ├── faq.md
 │   ├── setup-discord.md
 │   ├── setup-env.md
 │   └── transcripts.md
@@ -180,6 +182,8 @@ OmegaBot is online
 │   │   │   ├── commandLoader.ts
 │   │   │   ├── fetchChannelMessages.ts
 │   │   │   └── interactionHandler.ts
+│   │   ├── faq
+│   │   │   └── type.ts
 │   │   ├── github
 │   │   │   ├── githubApi.ts
 │   │   │   ├── githubClient.ts
@@ -209,7 +213,6 @@ OmegaBot is online
 │   ├── bot.ts
 │   └── registerCommands.ts
 ├── .env.example
-├── .eslintcache
 ├── .gitignore
 ├── .prettierignore
 ├── .prettierrc.yml

docs/faq.md

@@ -0,0 +1,87 @@
+# FAQ System Design
+
+This document defines how FAQs are stored, identified, and managed inside **OmegaBot**.
+
+The goal is to keep FAQs:
+
+- Easy to manage
+- Safe for Discord limits
+- Auditable
+- Simple to migrate to a database later
+
+---
+
+## Storage Model
+
+FAQs are stored in a file-based JSON store:
+
+```
+data/faqs.json
+```
+
+This file is the single source of truth for all FAQ entries.
+
+---
+
+## FAQ Entry Schema
+
+Each FAQ entry follows this schema:
+
+```ts
+type FaqEntry = {
+  key: string;
+  title: string;
+  body: string;
+  tags: string[];
+  createdAt: string;
+  updatedAt: string;
+  createdBy: string;
+  updatedBy: string;
+  usageCount: number;
+};
+
+type FaqStore = {
+  version: 1;
+  entries: Record<string, FaqEntry>;
+};
+```
+
+---
+
+## Key Format and Limits
+
+- Lowercase only
+- Letters, numbers, and dashes only
+- No spaces
+- Immutable once created
+- Max length: 48 characters
+
+---
+
+## Size Limits
+
+| Field | Limit      |
+| ----- | ---------- |
+| title | 80 chars   |
+| body  | 4000 chars |
+| tags  | 10 max     |
+
+---
+
+## Command Expectations
+
+- `/faq add` validates input and initializes metadata
+- `/faq get` increments usage count
+- `/faq list` shows keys + titles
+- `/faq remove` deletes entry (permission-gated)
+
+---
+
+## Future Plans
+
+- Database storage
+- Search
+- Role-based visibility
+- Audit history
+
+FAQs are treated as shared operational knowledge.

src/services/faq/type.ts

@@ -0,0 +1,16 @@
+export type FaqEntry = {
+  key: string;
+  title: string;
+  body: string;
+  tags: string[];
+  createdAt: string;
+  updatedAt: string;
+  createdBy: string;
+  updatedBy: string;
+  usageCount: number;
+};
+
+export type FaqStoreV1 = {
+  version: 1;
+  entries: Record<string, FaqEntry>;
+};