---
title: Nomena
---

Nomena (hereinafter the "Application") is a Discord bot that generates creative project ideas by providing AI-powered project names with explanations and custom anime mascot images. The Application leverages Claude AI for intelligent text generation and Google Gemini for custom avatar creation.

## 1. User Documentation

This section is for those interacting with a live instance of the Application.

### 1.1. Overview

Nomena is a Discord bot designed to help generate creative project ideas. When mentioned in Discord, the bot generates fitting project names based on your description and creates a unique anime mascot image to serve as the project's avatar.

### 1.2. Access Requirements

Currently, the Application is configured for single-user access. Users must be authorised by the bot owner to interact with Nomena. If you attempt to use the bot without authorisation, you will receive a message indicating that the bot can only generate project ideas for authorised users.

### 1.3. How to Use

#### Basic Usage

To generate a project idea, mention the bot in a Discord channel followed by your project description:

```
@Nomena <your project description>
```

**Example:**
```
@Nomena A web application for tracking daily water intake and sending reminders
```

#### What You'll Receive

After mentioning the bot, you will receive a response containing:

1. **Project Names**: 1-5 fitting project names generated based on your description
2. **Name Explanations**: Reasoning for why each name was chosen
3. **Project Description**: Your original input, echoed back for reference
4. **Mascot Image**: A full-body anime character image (3:4 aspect ratio, white background) attached as `avatar.png`

The bot will display a typing indicator while processing your request, which typically takes a few seconds.

#### Unique Names

The Application automatically checks against a database of existing project names to ensure that generated names are unique and don't conflict with previously created projects.

#### Image Generation Limitations

In rare cases, image generation may fail due to API limitations or content restrictions. When this occurs, you will still receive the project names and descriptions, with a message indicating that the image could not be generated.

### 1.4. Best Practices

- **Be Descriptive**: Provide clear, detailed descriptions of your project idea for better name suggestions
- **Include Context**: Mention the project's purpose, target audience, or key features
- **One Request at a Time**: Wait for the bot to respond before sending additional requests
- **Respect Rate Limits**: Avoid excessive requests in rapid succession

### 1.5. Example Interactions

**Request:**
```
@Nomena A mobile app for learning Japanese vocabulary through spaced repetition
```

**Response:**
```
Project Name: KanjiFlow, NihongoLoop, or MemoryMichi

Explanations:
- KanjiFlow: Combines "Kanji" (Japanese characters) with "Flow" (smooth progression)
- NihongoLoop: Uses "Nihongo" (Japanese language) with "Loop" (repetition)
- MemoryMichi: Blends "Memory" with "Michi" (path in Japanese)

Project Description: A mobile app for learning Japanese vocabulary through spaced repetition

[Attached: avatar.png - anime mascot image]
```

## 2. Technical Documentation

This section is for those interested in running their own instance of the Application.

### 2.1. System Requirements

- **Node.js**: Version 18.x or higher
- **Package Manager**: pnpm 10.19.0 (recommended) or npm
- **Operating System**: Linux, macOS, or Windows
- **API Keys**: Valid API keys for required services (see Environment Variables)

### 2.2. Technology Stack

The Application is built with the following technologies:

**Core Technologies:**
- **TypeScript** (v5.9.3): Type-safe JavaScript development
- **Discord.js** (v14.24.2): Discord bot framework and API wrapper
- **Anthropic SDK** (@anthropic-ai/sdk v0.68.0): Claude AI integration for text generation
- **Google GenAI** (@google/genai v1.28.0): Gemini AI integration for image generation

**Development Tools:**
- **ESLint** (v9.38.0): Code quality and linting
- **Custom Configurations**: @nhcarrigan/eslint-config, @nhcarrigan/typescript-config

**Utilities:**
- **@nhcarrigan/logger** (v1.1.1): Custom logging utility with Discord Analytics integration
- **@nhcarrigan/discord-analytics** (v0.0.6): Analytics tracking

### 2.3. Installation

1. **Clone the repository:**
   ```bash
   git clone <repository-url>
   cd nomena
   ```

2. **Install dependencies:**
   ```bash
   pnpm install
   ```

   Or using npm:
   ```bash
   npm install
   ```

3. **Configure environment variables** (see section 2.4)

4. **Build the application:**
   ```bash
   pnpm run build
   ```

### 2.4. Environment Variables

Create a `prod.env` file in the project root with the following variables:

```sh
# Required: Anthropic API key for Claude AI
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Required: Google Gemini API key for image generation
GEMINI_API_KEY=your_gemini_api_key_here

# Required: Discord bot token
DISCORD_TOKEN=your_discord_bot_token_here

# Required: Logger token for Discord Analytics
LOG_TOKEN=your_log_token_here
```

**API Key Acquisition:**
- **Anthropic API Key**: Sign up at https://console.anthropic.com/
- **Gemini API Key**: Obtain from Google AI Studio at https://makersuite.google.com/
- **Discord Bot Token**: Create a bot at https://discord.com/developers/applications
- **Log Token**: Refer to @nhcarrigan/logger documentation

**All environment variables are required.** The Application will throw an error and refuse to start if any are missing.

### 2.5. Discord Bot Configuration

When creating your Discord bot at https://discord.com/developers/applications, ensure the following:

**Required Intents:**
- `Guilds`: Access to guild information
- `Guild Messages`: Receive messages in guilds
- `Message Content`: Read full message content (privileged intent)

**Bot Permissions:**
- Read Messages/View Channels
- Send Messages
- Attach Files
- Read Message History

**Note:** The Message Content intent is a privileged intent and must be enabled in the Discord Developer Portal.

### 2.6. Customization

#### User Access Control

By default, the bot is configured for single-user access. To modify access control, edit `src/index.ts:44`:

```typescript
if (message.author.id !== "YOUR_DISCORD_USER_ID") {
  await message.reply("Sorry, I can only generate project ideas for authorised users.");
  return;
}
```

You can:
- Replace the user ID with your own Discord user ID
- Remove the check entirely to allow all users
- Implement role-based access control
- Add a whitelist of authorised user IDs

#### Bot Mention ID

Update the bot mention ID in `src/index.ts:37` to match your bot's ID:

```typescript
if (!message.mentions.has("YOUR_BOT_ID", {
  ignoreEveryone:    true,
  ignoreRepliedUser: true,
  ignoreRoles:       true,
})) {
  return;
}
```

Find your bot's ID in the Discord Developer Portal.

#### AI Model Configuration

To modify the AI models used:

**Text Generation (src/classes/ai.ts:78):**
```typescript
model: "claude-sonnet-4-5-20250929"  // Change to any available Claude model
```

**Image Generation (src/classes/ai.ts:100):**
```typescript
model: "gemini-2.5-flash-image"  // Change to any available Gemini model
```

**Token Limits (src/classes/ai.ts:71):**
```typescript
max_tokens: 1000  // Adjust based on your needs
```

#### Project Name Uniqueness Check

The bot fetches existing project names from `https://data.nhcarrigan.com/projects.json`. To use your own data source, modify `src/classes/ai.ts:42-43`:

```typescript
const projectRequest = await fetch("YOUR_DATA_SOURCE_URL");
```

Ensure your data source returns an array of objects with a `name` property:
```json
[
  { "name": "ProjectOne" },
  { "name": "ProjectTwo" }
]
```

To disable the uniqueness check entirely, comment out or remove the fetch logic and modify the system prompt accordingly.

#### Image Generation Prompts

Customise the mascot generation prompt in `src/classes/ai.ts:95-97`:

```typescript
systemInstruction: `Your custom prompt here`
```

Adjust the aspect ratio in `src/classes/ai.ts:95`:

```typescript
imageConfig: { aspectRatio: "3:4" }  // Options: "1:1", "16:9", "9:16", etc.
```

### 2.7. Running the Application

**Development Mode:**
```bash
pnpm run build && node prod/index.js
```

**Production Mode (with 1Password integration):**
```bash
pnpm start
```

This runs: `op run --env-file=prod.env -- node prod/index.js`

**Without 1Password:**

If you're not using 1Password for secret management, modify the `start` script in `package.json`:

```json
"start": "node prod/index.js"
```

Then ensure your environment variables are loaded through your preferred method (e.g., dotenv, system environment variables).

### 2.8. Development Workflow

**Code Linting:**
```bash
pnpm run lint
```

Note: The lint script uses `--max-warnings 0`, meaning any warnings will cause the command to fail.

**Build Process:**
```bash
pnpm run build
```

This compiles TypeScript files from `src/` to `prod/`.

**Testing:**
```bash
pnpm test
```

Note: Currently no tests are implemented. This command returns successfully with exit code 0.

### 2.9. Project Structure

```
nomena/
├── src/
│   ├── index.ts              # Main entry point, Discord bot initialization
│   └── classes/
│       └── ai.ts             # AI utility class for text and image generation
├── prod/                     # Compiled JavaScript output (gitignored)
├── node_modules/             # Dependencies
├── prod.env                  # Environment variables (gitignored)
├── package.json              # Project metadata and dependencies
├── tsconfig.json             # TypeScript configuration
├── eslint.config.js          # ESLint configuration
├── .gitignore                # Git ignore rules
├── LICENSE.md                # License information
├── CONTRIBUTING.md           # Contributing guidelines
├── CODE_OF_CONDUCT.md        # Code of conduct
├── PRIVACY.md                # Privacy policy
├── SECURITY.md               # Security policy
└── TERMS.md                  # Terms of service
```

### 2.10. Logging and Monitoring

The Application uses @nhcarrigan/logger for logging with Discord Analytics integration. Logs include:

- Bot startup events (debug level)
- Error tracking (when enabled in the logger)
- Custom analytics events (when configured)

To modify logging behaviour, update the logger initialization in `src/index.ts:21`:

```typescript
const logger = new Logger("Nomena", process.env.LOG_TOKEN);
```

### 2.11. Troubleshooting

**Bot doesn't respond:**
- Verify the bot has the Message Content intent enabled
- Check that the bot mention ID in the code matches your bot's ID
- Ensure the bot has permission to read and send messages in the channel

**Environment variable errors:**
- Verify all four required environment variables are set
- Check for typos in variable names
- Ensure the `prod.env` file is in the project root

**Image generation failures:**
- Verify your Gemini API key is valid and has sufficient quota
- Check if the prompt violates content policies
- Review Google AI Studio logs for detailed error messages

**TypeScript compilation errors:**
- Ensure you're using Node.js 18.x or higher
- Delete `node_modules` and `prod` directories, then reinstall: `pnpm install && pnpm run build`

**Permission errors:**
- Verify bot permissions in Discord server settings
- Ensure the bot role has sufficient privileges

### 2.12. Production Deployment

**Recommended Setup:**
- Use a process manager (PM2, systemd, Docker)
- Implement log rotation
- Set up monitoring and alerting
- Use environment-specific configuration files
- Implement graceful shutdown handling
- Consider using a reverse proxy if exposing any HTTP endpoints

**Example PM2 Configuration:**

```json
{
  "apps": [{
    "name": "nomena",
    "script": "prod/index.js",
    "env_file": "prod.env",
    "instances": 1,
    "autorestart": true,
    "watch": false,
    "max_memory_restart": "1G"
  }]
}
```

**Docker Deployment:**

While no Dockerfile is provided, a basic setup would include:
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install --frozen-lockfile
COPY . .
RUN pnpm run build
CMD ["node", "prod/index.js"]
```

### 2.13. API Rate Limits and Costs

**Anthropic (Claude AI):**
- Free tier: Limited requests per month
- Paid tier: Pay-per-token pricing
- Token usage: ~100-500 tokens per request (depending on response length)
- Rate limits: Vary by tier

**Google Gemini:**
- Free tier: Limited image generations per day
- Paid tier: Pay-per-generation pricing
- Rate limits: Vary by model and tier

**Discord:**
- 50 requests per second per bot
- Additional limits on message size and file attachments

Monitor your usage to avoid unexpected costs or service interruptions.

## 3. Legal Documentation

This section is for expansions to our legal policies specific to the Application.

### 3.1. License

This Application is licensed under Naomi's Public Licence. The full licence text is available at:
https://docs.nhcarrigan.com/#/license

Copyright is held by Naomi Carrigan.

### 3.2. Privacy Policy

The Application's privacy practices are governed by the global privacy policy available at:
https://docs.nhcarrigan.com/#/privacy

**Application-Specific Privacy Considerations:**

- **User Messages**: Discord messages mentioning the bot are processed to extract project descriptions
- **API Data**: Project descriptions are sent to third-party APIs (Anthropic and Google) for processing
- **Generated Content**: Project names and images are generated and stored temporarily in Discord
- **Logging**: Basic debug information is logged via Discord Analytics
- **User Identification**: Discord user IDs are checked for access control purposes

**Data Retention:**
- Messages are not stored beyond the request lifecycle
- Generated images are stored on Discord's servers as message attachments
- Logs may retain basic event information per the logger configuration

**Third-Party Services:**
- Anthropic (Claude AI): Processes project descriptions to generate names
- Google (Gemini AI): Processes project descriptions to generate images
- Discord Analytics: Receives basic logging information

Users should review the privacy policies of these third-party services.

### 3.3. Security Policy

The Application's security practices follow the global security policy available at:
https://docs.nhcarrigan.com/#/security

**Application-Specific Security Measures:**

- **Access Control**: User ID verification limits bot usage to authorised individuals
- **Environment Variables**: Sensitive API keys are stored in environment variables, not in code
- **Input Validation**: User input is sanitized before being sent to AI APIs
- **Error Handling**: Errors are caught and handled gracefully without exposing sensitive information

**Security Considerations for Self-Hosted Instances:**

- Keep dependencies updated to patch security vulnerabilities
- Protect your `prod.env` file and never commit it to version control
- Use strong, unique API keys
- Monitor API usage for unusual activity
- Implement rate limiting if exposing the bot publicly
- Review Discord permissions to follow the principle of least privilege

**Reporting Security Vulnerabilities:**

If you discover a security vulnerability, please report it following the guidelines at:
https://docs.nhcarrigan.com/#/security

### 3.4. Terms of Service

General terms of service can be found in the `TERMS.md` file in the repository.

**Application-Specific Terms:**

- The Application generates content using AI, which may occasionally produce unexpected or inappropriate results
- Generated project names are suggestions only and may not be suitable for all use cases
- Users are responsible for verifying that generated names are available for use (trademark searches, domain availability, etc.)
- The Application makes best efforts to generate unique names but does not guarantee uniqueness outside of the internal project database
- Generated images are created by AI and may not always match expectations or requirements

### 3.5. Content Policy

**Generated Content:**
- AI-generated names and images are provided "as-is"
- The Application attempts to filter inappropriate content through AI safety measures
- Users should review generated content before using it in production

**Image Generation:**
- Images are generated in an anime art style
- The system prompt instructs the AI to create appropriate content
- Image generation may fail if content policies are violated

### 3.6. Code of Conduct

Contributors and users are expected to follow the code of conduct available at:
https://docs.nhcarrigan.com/#/coc

## 4. Contributing Documentation

This section is for documentation related to contributing to the Application's codebase.

### 4.1. General Contributing Guidelines

General contributing guidelines can be found at:
https://docs.nhcarrigan.com/#/contributing

Please review these guidelines before contributing to the Application.

### 4.2. Development Setup

Follow the installation instructions in Section 2.3 (Installation) to set up your development environment.

**Additional Development Tools:**

- **ESLint**: Code is linted using @nhcarrigan/eslint-config
- **TypeScript**: Strong typing is enforced throughout the codebase
- **Code Style**: Follow the existing code style and conventions

### 4.3. Code Quality Standards

**Linting:**
- All code must pass `pnpm run lint` without warnings
- The project uses ESLint with maximum warnings set to 0

**TypeScript:**
- Use explicit types where appropriate
- Avoid `any` types unless absolutely necessary
- Document complex type definitions

**Comments and Documentation:**
- Use JSDoc comments for public methods and classes
- Include file headers with copyright, license, and author information
- Comment complex logic or non-obvious implementations

**Example File Header:**
```typescript
/**
 * @copyright NHCarrigan
 * @license Naomi's Public Licence
 * @author Naomi Carrigan
 */
```

### 4.4. Contribution Workflow

1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/your-feature-name`
3. **Make your changes**
4. **Test your changes**: Build and run the application locally
5. **Lint your code**: `pnpm run lint`
6. **Commit your changes**: Follow conventional commit format
7. **Push to your fork**: `git push origin feature/your-feature-name`
8. **Open a pull request**

### 4.5. Pull Request Guidelines

**Before Submitting:**
- Ensure all code passes linting
- Test the application thoroughly
- Update documentation if necessary
- Keep commits atomic and well-described

**PR Description Should Include:**
- Summary of changes
- Motivation for the changes
- Any breaking changes
- Testing performed
- Screenshots (for UI changes, if applicable)

### 4.6. Areas for Contribution

**Feature Enhancements:**
- Multi-user support improvements
- Additional AI model options
- Customizable response formats
- Project name filtering options
- Image style customisation

**Code Quality:**
- Adding unit tests
- Improving error handling
- Performance optimisations
- Code documentation

**Bug Fixes:**
- Reporting and fixing bugs
- Improving edge case handling
- Fixing typos or documentation errors

**Documentation:**
- Expanding user guides
- Adding code examples
- Improving setup instructions
- Creating video tutorials

### 4.7. Testing Guidelines

**Currently, the Application has no automated tests.** Contributors are encouraged to:

- Add unit tests for the `Ai` class (src/classes/ai.ts)
- Add integration tests for Discord bot functionality
- Test with various project descriptions and edge cases
- Verify image generation works with different prompts

**Recommended Testing Frameworks:**
- Jest for unit testing
- Discord.js test utilities for bot testing

### 4.8. Commit Message Format

Follow conventional commit format:

```
<type>(<scope>): <subject>

<body>

<footer>
```

**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `test`: Adding tests
- `chore`: Maintenance tasks

**Examples:**
```
feat(ai): add support for custom image aspect ratios

docs(readme): update installation instructions

fix(bot): handle missing image generation gracefully
```

### 4.9. Review Process

- Pull requests will be reviewed by project maintainers
- Feedback may be provided for changes or improvements
- Once approved, PRs will be merged by maintainers
- Contributors will be credited in release notes

### 4.10. Getting Help

If you need help contributing:

- Review existing issues and pull requests
- Check the documentation at https://docs.nhcarrigan.com/
- Open a discussion in the repository
- Reach out to maintainers

### 4.11. Code Organization

When adding new features, follow the existing structure:

```
src/
├── index.ts              # Main entry point, keep minimal
├── classes/              # Utility classes
│   └── ai.ts            # AI-related functionality
└── (future additions)    # Commands, utilities, etc.
```

**Best Practices:**
- Keep `index.ts` focused on bot initialization and event handling
- Create separate classes for distinct functionality
- Use dependency injection where appropriate
- Avoid tight coupling between components

### 4.12. Dependencies

**Adding Dependencies:**
- Prefer well-maintained packages with active communities
- Check licenses for compatibility
- Keep dependencies minimal
- Document why dependencies are needed

**Updating Dependencies:**
- Test thoroughly after updates
- Check for breaking changes
- Update documentation if APIs change

---

## Appendix

### A. Frequently Asked Questions

**Q: Can I use this bot in my Discord server?**
A: The bot is currently configured for single-user access. You can fork the repository and run your own instance with modified access controls.

**Q: Why does the bot only respond to one user?**
A: This is a deliberate design choice for the official instance. Self-hosted instances can modify access controls in the code.

**Q: Can I change the art style of generated images?**
A: Yes, modify the system instruction in `src/classes/ai.ts:95-97` to specify different art styles.

**Q: How much does it cost to run?**
A: Costs depend on API usage. Both Anthropic and Google offer free tiers, but high-volume usage may incur costs.

**Q: Can I use a different AI model?**
A: Yes, modify the model names in the code. Ensure compatibility with the SDK methods used.

**Q: Why did image generation fail?**
A: Common reasons include API quota limits, content policy violations, or temporary service unavailability.

**Q: How do I get my Discord user ID?**
A: Enable Developer Mode in Discord settings, then right-click your username and select "Copy User ID".

**Q: Can I deploy this on a free tier service?**
A: Yes, the bot can run on services like Heroku (legacy), Railway, Render, or Fly.io, subject to their free tier limitations.

### B. Glossary

- **AI**: Artificial Intelligence
- **API**: Application Programming Interface
- **Bot**: Automated Discord application
- **Claude**: Anthropic's AI language model
- **Discord**: Communication platform
- **ESLint**: JavaScript linting tool
- **Gemini**: Google's AI model family
- **Intent**: Discord API permission flag
- **Mascot**: Representative character image
- **pnpm**: Fast, disk space efficient package manager
- **TypeScript**: Typed superset of JavaScript

### C. Version History

- **v1.0.0**: Initial release
  - Claude AI integration for project name generation
  - Google Gemini integration for mascot image generation
  - Discord bot functionality
  - Single-user access control
  - Uniqueness checking against existing projects

### D. Credits

- **Author**: Naomi Carrigan
- **License**: Naomi's Public Licence
- **Dependencies**: See package.json for full list
- **Special Thanks**: Anthropic, Google, and Discord.js contributors

### E. Additional Resources

- **Anthropic Documentation**: https://docs.anthropic.com/
- **Google AI Documentation**: https://ai.google.dev/
- **Discord.js Guide**: https://discordjs.guide/
- **TypeScript Documentation**: https://www.typescriptlang.org/docs/
- **Author's Documentation Hub**: https://docs.nhcarrigan.com/

---

**Documentation Version**: 1.0.0
