bitcashorg
diff --git a/‎.github/copilot-instructions.md‎
Lines changed: 293 additions & 2 deletions b/‎.github/copilot-instructions.md‎
Lines changed: 293 additions & 2 deletions
diff --git a/‎.github/instructions/copilot-instructions.md‎
Lines changed: 455 additions & 0 deletions b/‎.github/instructions/copilot-instructions.md‎
Lines changed: 455 additions & 0 deletions
diff --git a/‎.gitignore‎
Lines changed: 4 additions & 1 deletion b/‎.gitignore‎
Lines changed: 4 additions & 1 deletion
diff --git a/‎.husky/commit-msg‎
Lines changed: 1 addition & 1 deletion b/‎.husky/commit-msg‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎AGENTS.md‎
Lines changed: 414 additions & 0 deletions b/‎AGENTS.md‎
Lines changed: 414 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 289 additions & 7 deletions b/‎CLAUDE.md‎
Lines changed: 289 additions & 7 deletions
diff --git a/‎README.md‎
Lines changed: 7 additions & 7 deletions b/‎README.md‎
Lines changed: 7 additions & 7 deletions
diff --git a/‎apps/hasura/README.md‎
Lines changed: 274 additions & 0 deletions b/‎apps/hasura/README.md‎
Lines changed: 274 additions & 0 deletions
@@ -16,4 +16,7 @@ bun.lockb
 
 gcp-serv-acct-key.json
 
-tsconfig.tsbuildinfo
+tsconfig.tsbuildinfo
+
+# Taskfile binary (should be installed per-environment)
+bin/task
@@ -1 +1 @@
-npx --no-install commitlint --edit "$1"
+bunx --no-install commitlint --edit "$1"
@@ -1,4 +1,4 @@
-# masterbots
+# <a href="https://deepwiki.com/bitcashorg/masterbots"><img src="https://deepwiki.com/badge.svg" width="164" height="164" alt="Ask DeepWiki"></a> MasterBots
 
 **MasterBots is a UX-focused open-source chatbot aggregator platform and alternative to ChatGPT.**
 
@@ -24,18 +24,18 @@ Contributors will earn platform credits that can be sold for cash.
 (Credits may get more valuable over time)
 
 Here is our public Trello board:
-https://trello.com/b/GDCm18zN/masterbots-chatbot-aggregator-development-board
+<https://trello.com/b/GDCm18zN/masterbots-chatbot-aggregator-development-board>
 
 ## Requirements
 
 - NodeJS. We recommend [nvm](https://github.com/nvm-sh/nvm) for version switching.
-- Hasura Cli https://hasura.io/docs/latest/hasura-cli/overview.
-- pnpm package manager https://pnpm.io/
+- Hasura Cli <https://hasura.io/docs/latest/hasura-cli/overview>.
+- pnpm package manager <https://pnpm.io/>
 - [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/)
-- Task manager https://taskfile.dev
-- Bun https://bun.sh/
+- Task manager <https://taskfile.dev>
+- Bun <https://bun.sh/>
 
-## Running the Backend:
+## Running the Backend
 
 In root folder, create an .env file based of .env_sample and the use `task` to execute the following commands to operate Hasura locally.
 
 
@@ -0,0 +1,274 @@
+# Hasura Backend
+
+This directory contains the Hasura GraphQL Engine configuration, migrations, metadata, and seeds for the Masterbots platform.
+
+## Overview
+
+The Hasura backend provides:
+- GraphQL API for all database operations
+- Database schema management through migrations
+- Metadata configuration for GraphQL schema customization
+- Seed data for initializing the database with required data
+
+## Directory Structure
+
+```
+apps/hasura/
+├── config.yaml          # Hasura project configuration
+├── metadata/            # GraphQL schema metadata and permissions
+├── migrations/          # Database schema migrations
+│   └── masterbots/     # Migration files (timestamped)
+└── seeds/              # Database seed files
+    └── masterbots/     # Seed SQL files (timestamped)
+```
+
+## Requirements
+
+- [Hasura CLI](https://hasura.io/docs/latest/hasura-cli/overview)
+- [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/)
+- [Task](https://taskfile.dev) - Task runner for executing common commands
+- PostgreSQL (running via Docker)
+
+## Common Commands
+
+All commands should be run from the project root directory using `task`:
+
+### Initial Setup
+
+```bash
+task boot      # First-time setup: starts DB + Hasura + applies migrations
+```
+
+This command:
+1. Starts PostgreSQL database container
+2. Waits for database to be ready (10 seconds)
+3. Starts Hasura container
+4. Waits for Hasura to be ready (30 seconds)
+5. Applies all migrations and metadata
+
+### Daily Operations
+
+```bash
+task up        # Start all services (database + Hasura)
+task down      # Stop all services and remove volumes
+task stop      # Stop all services (preserve data)
+task console   # Open Hasura console (recommended for schema changes)
+```
+
+### Database Operations
+
+```bash
+task migrate   # Apply database migrations and metadata
+task seed      # Apply seed data to the database
+task reload    # Full restart with log tailing
+```
+
+## Seeds
+
+### What Are Seeds?
+
+Seeds are SQL files that populate the database with initial or reference data. They are essential for:
+
+1. **Setting up development environments** with consistent data
+2. **Populating enum tables** with predefined values (e.g., message types, complexity levels)
+3. **Creating test users** and sample content
+4. **Initializing configuration data** (e.g., chatbot metadata, categories)
+
+### Seed Files Overview
+
+Seeds in `apps/hasura/seeds/masterbots/` are organized by timestamp and purpose:
+
+| Seed File | Purpose |
+|-----------|---------|
+| `1724269974513_init_config_seeds.sql` | Configuration enums (message types, complexity, length, tone) |
+| `1724270512560_init_users_seeds.sql` | Initial user accounts (commented out for security) |
+| `1724271272084_init_threads_seeds.sql` | Sample conversation threads |
+| `1724271332200_init_messages_seeds.sql` | Sample messages in threads |
+| `1738186795715_init_chatbot_metadata_seeds.sql` | Chatbot metadata (deprecated) |
+| `1740386119320_init_domain_enum.sql` | Domain enumeration values |
+| `1740386119321_init_chatbot_metadata_seeds.sql` | Updated chatbot metadata |
+| `1746466168385_init_category_enum.sql` | Category enumeration values |
+| `1746466170867_init_subcategory_enum.sql` | Subcategory enumeration values |
+| `1746466178152_init_tag_enum_pt_1.sql` | Tag enumeration values (part 1 of 2) |
+| `1746466178153_init_tag_enum_pt_2.sql` | Tag enumeration values (part 2 of 2) |
+| `1746466541637_init_example_pt_*.sql` | Example data (parts 1-14) |
+
+### Best Practices for Seeds
+
+#### 1. Use ON CONFLICT Clauses
+
+All seed INSERT statements should use `ON CONFLICT` clauses to make them idempotent:
+
+```sql
+INSERT INTO public.message_type_enum VALUES ('user')
+ON CONFLICT (value) DO NOTHING;
+```
+
+This ensures seeds can be safely re-applied without causing errors or duplicate data.
+
+#### 2. Maintain Timestamp Ordering
+
+Seed files are executed in alphabetical order (timestamp-based). Ensure dependencies are respected:
+- Configuration and enum seeds should run first
+- Reference data should follow
+- Relational data with foreign keys should run last
+
+#### 3. Keep Large Seeds Split
+
+Very large seed files (>20MB) should be split into multiple parts to:
+- Improve version control diff performance
+- Reduce memory usage during application
+- Make debugging easier
+
+Example: `init_example_pt_1.sql` through `init_example_pt_14.sql`
+
+#### 4. Comment Sensitive Data
+
+User credentials and personal information should be commented out in seed files:
+
+```sql
+-- INSERT INTO public."user" 
+-- (username, email, password, ...) 
+-- VALUES ('user', 'email@example.com', 'password', ...)
+```
+
+### Seed Debugging
+
+#### Problem: Console Output Flooding
+
+When running `task seed`, the console can be flooded with thousands of lines of output, making it difficult to identify errors or warnings.
+
+#### Solution: Redirect Output to a Log File
+
+Redirect both stdout and stderr to a log file for easier debugging:
+
+```bash
+task seed > seed.log 2>&1
+```
+
+This command:
+- Redirects standard output (`stdout`) to `seed.log`
+- Redirects error output (`stderr`) to the same file (`2>&1`)
+- Allows you to review the output at your own pace using a text editor
+
+After running this command, you can:
+```bash
+# View the entire log
+cat seed.log
+
+# Search for errors
+grep -i error seed.log
+
+# Search for warnings
+grep -i warning seed.log
+
+# View the last 50 lines
+tail -n 50 seed.log
+```
+
+#### Manual Seed Application (Alternative)
+
+If you need more control over the seeding process, you can run the Hasura CLI directly:
+
+```bash
+hasura seeds apply --project apps/hasura --database-name masterbots --admin-secret ${HASURA_GRAPHQL_ADMIN_SECRET}
+```
+
+**Note:** This command is the same as `task seed` but requires you to:
+- Ensure the `HASURA_GRAPHQL_ADMIN_SECRET` environment variable is set
+- Be in the project root directory
+- Have Hasura running
+
+## Common Issues and Troubleshooting
+
+### Issue: Seeds Fail with Duplicate Key Errors
+
+**Cause:** Seeds are being applied to a database that already has the data.
+
+**Solution:** Ensure all INSERT statements use `ON CONFLICT` clauses:
+```sql
+INSERT INTO table_name VALUES (...)
+ON CONFLICT (unique_column) DO NOTHING;
+```
+
+### Issue: Seeds Fail with Foreign Key Constraint Violations
+
+**Cause:** Seeds are being applied in the wrong order, or referenced data doesn't exist.
+
+**Solution:** 
+1. Check the timestamp order of seed files
+2. Ensure all dependent data is seeded first
+3. Verify migrations have been applied before seeds
+
+### Issue: Hasura Console Shows "Schema/Metadata Inconsistent"
+
+**Cause:** Migrations or metadata changes haven't been applied.
+
+**Solution:**
+```bash
+task migrate
+```
+
+### Issue: Cannot Connect to Database
+
+**Cause:** PostgreSQL container isn't running or hasn't finished initializing.
+
+**Solution:**
+1. Check if containers are running: `docker ps`
+2. Restart services: `task down && task boot`
+3. Check logs: `docker compose logs postgres`
+
+## Development Workflow
+
+### Making Schema Changes
+
+**Always use the Hasura Console** for schema changes to ensure migrations and metadata are properly tracked:
+
+```bash
+task console
+```
+
+This opens the Hasura Console at `http://localhost:9695` where you can:
+- Modify tables and relationships
+- Configure permissions
+- Test GraphQL queries
+- Automatically generate migration files
+
+**Never** edit migration files manually unless you know exactly what you're doing.
+
+### Adding New Seeds
+
+1. Create a new SQL file in `apps/hasura/seeds/masterbots/`
+2. Use timestamp format: `{timestamp}_{description}.sql`
+3. Include `SET check_function_bodies = false;` at the top
+4. Use `ON CONFLICT` clauses for all INSERT statements
+5. Test the seed: `task seed`
+6. Commit the seed file to version control
+
+### Applying Changes from Other Developers
+
+When pulling changes that include new migrations or seeds:
+
+```bash
+git pull
+task migrate   # Apply new migrations and metadata
+task seed      # Apply new seeds
+```
+
+## Environment Variables
+
+The following environment variables are required (defined in root `.env` file):
+
+- `HASURA_GRAPHQL_ADMIN_SECRET` - Admin secret for Hasura (required for all operations)
+- `HASURA_GRAPHQL_DATABASE_URL` - PostgreSQL connection string
+- `HASURA_GRAPHQL_ENABLE_CONSOLE` - Enable/disable built-in console
+- `HASURA_GRAPHQL_JWT_SECRET` - JWT secret for authentication
+
+See `.env_sample` in the project root for example values.
+
+## Additional Resources
+
+- [Hasura Documentation](https://hasura.io/docs/)
+- [Hasura CLI Reference](https://hasura.io/docs/latest/hasura-cli/commands/)
+- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
+- [Masterbots Main README](../../README.md)
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-npx --no-install commitlint --edit "$1"`
	`1`	`+bunx --no-install commitlint --edit "$1"`