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:

   git clone <repository-url>
   cd nomena

2. Install dependencies:

   pnpm install

   Or using npm:

   npm install

3. Configure environment variables (see section 2.4)

4. Build the application:

   pnpm run build

2.4. Environment Variables

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

# 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. Customisation

User Access Control

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

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:

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):

model: "claude-sonnet-4-5-20250929"  // Change to any available Claude model

Image Generation (src/classes/ai.ts:100):

model: "gemini-2.5-flash-image"  // Change to any available Gemini model

Token Limits (src/classes/ai.ts:71):

max_tokens: 1000  // Adjust based on your needs

Project Name Uniqueness Check

The bot checks suggested names against a list of existing project names, which it fetches from a URL set in src/classes/ai.ts. The default URL pointed at our former data API, which has been retired, so you need to set your own data source:

const projectRequest = await fetch("YOUR_DATA_SOURCE_URL");

Ensure your data source returns an array of objects with a name property:

[
  { "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:

systemInstruction: `Your custom prompt here`

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

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

2.7. Running the Application

Development Mode:

pnpm run build && node prod/index.js

Production Mode (with 1Password integration):

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:

"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:

pnpm run lint

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

Build Process:

pnpm run build

This compiles TypeScript files from src/ to prod/.

Testing:

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 initialisation in src/index.ts:21:

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:

{
  "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:

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.spellware.dev/#/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.spellware.dev/#/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.spellware.dev/#/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 sanitised 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.spellware.dev/#/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.spellware.dev/#/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.spellware.dev/#/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:

/**
 * @copyright SpellWare
 * @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.spellware.dev/
• Open a discussion in the repository
• Reach out to maintainers

4.11. Code Organisation

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 initialisation 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.spellware.dev/

---

Documentation Version: 1.0.0