Contributing

AI Supreme Council welcomes contributions across several areas: the model registry, translations, documentation, mini-programs, and core code. This guide covers each contribution path.

Areas for Contribution

Area	Difficulty	Files	Validation
Model Registry	Easy	registry/models.json	python3 registry/validate.py
Translations	Easy	registry/locale/{lang}.json	python3 registry/locale/validate_locale.py
Documentation	Easy	doc.aiscouncil.com/site/docs/	Local preview with npm start
Mini-Programs	Medium	manifest.json + index.html	python3 registry/validate.py packages
Bug Fixes / Features	Medium-Hard	src/*.js, modules/*/index.ts	./build.sh && npm test

Model Registry

The model registry (registry/models.json) is a community-maintained list of LLM providers and models. Adding a new model is the easiest way to contribute.

Adding a Model

1. Fork the repository
2. Edit registry/models.json -- add your model under the appropriate provider
3. Validate:

python3 registry/validate.py

4. Submit a pull request

Model Entry Format

Each model requires these fields:

{
  "id": "model-id-from-provider",
  "name": "Human-Readable Name",
  "provider": "provider-id",
  "context": 128000,
  "maxOutput": 8192,
  "pricing": { "input": 3.0, "output": 15.0 },
  "capabilities": ["streaming", "vision", "tools"],
  "tier": "paid"
}

The validation script checks for:

• Valid JSON structure
• All required fields present (id, name, provider, context, maxOutput, pricing, capabilities, tier)
• No duplicate model IDs
• Capabilities from the allowed set: vision, tools, streaming, json_mode, reasoning, code
• Tier from the allowed set: free, paid, enterprise

تلميح

Check the existing entries in models.json for examples. Match the formatting style (2-space indent, fields in the same order) for clean diffs.

Translations

The app uses community-contributed locale files for internationalization. Each locale file translates the wizard and UI strings.

Adding or Updating a Translation

1. Copy registry/locale/en.json to registry/locale/{lang}.json (use ISO 639-1 codes: es, zh, ar, fr, etc.)
2. Translate all string values (the right side of each key-value pair)
3. Update _meta.lang and _meta.name
4. Validate:

python3 registry/locale/validate_locale.py registry/locale/{lang}.json

5. Submit a pull request

Translation Rules

• Do translate: All string values and _meta.name
• Do not change: Key names, _meta.lang code, _meta.version, template variables inside {curly braces}

Template variables like {name}, {count}, and {error} are replaced at runtime. Keep them exactly as they appear in the English source.

{
  "_meta": { "lang": "es", "name": "Espanol", "version": 1, "module": "wizard" },
  "createProfile": "Crear Perfil de IA",
  "operator": "Operador: {name}",
  "modelsSelected": "{count} seleccionados:"
}

معلومات

See registry/locale/TRANSLATING.md for the full translation guide, including character encoding rules and priority languages.

Currently Needed Languages

Complete translations exist for English, Spanish, Chinese, Arabic, French, Portuguese, Japanese, Korean, German, and Russian. Translations are still needed for: Hindi, Turkish, Ukrainian, Thai, Polish, Italian, Dutch, Indonesian, and Vietnamese.

Documentation

Documentation lives in the Docusaurus site at doc.aiscouncil.com/site/docs/.

Editing Docs

1. Edit or create Markdown files in doc.aiscouncil.com/site/docs/
2. Preview locally:

cd doc.aiscouncil.com/site
npm install
npm start

3. If adding a new page, register it in doc.aiscouncil.com/site/sidebars.ts
4. Submit a pull request

Doc Conventions

• Use frontmatter with sidebar_position, title, and description
• Use :::tip, :::info, :::warning admonitions for callouts
• Use tables for structured comparisons
• Include command examples where applicable
• Keep prose direct and concise

Mini-Programs

Mini-programs are sandboxed web apps that run inside the AI Supreme Council platform via iframes.

Creating a Mini-Program

1. Create a manifest.json:

{
  "name": "my-app",
  "version": "1.0.0",
  "abi": 1,
  "type": "mini-program",
  "title": "My App",
  "description": "What my app does",
  "entry": "index.html",
  "base_url": "https://your-cdn.com/my-app/",
  "permissions": ["storage"]
}

2. Create index.html using the window.ais SDK:

<!DOCTYPE html>
<html>
<body>
  <h1>My App</h1>
  <script>
    ais.ready(() => {
      ais.ui.toast('Hello from my app!');
    });
  </script>
</body>
</html>

3. Host your files on any CDN (GitHub Pages, Cloudflare Pages, Vercel)

4. Test locally by installing via manifest URL:

AIS.MiniPrograms.install('https://your-cdn.com/my-app/manifest.json');

Publishing to the Registry

1. Add your app entry to registry/packages.json
2. Validate:

python3 registry/validate.py packages

3. Submit a pull request

See the SDK documentation and sdk/ais.d.ts for the full mini-program API.

تلميح

The examples/hello-world/ directory contains a complete working mini-program you can use as a starting point.

Code Contributions

Development Setup

git clone https://github.com/nicholasgasior/bcz.git
cd bcz
npm install
./build.sh
npm test

Edit-Build-Test Cycle

1. Edit source files in src/ (never edit index.html directly)
2. Build: ./build.sh
3. Test: npm test
4. Verify: ./build.sh --check

For TypeScript modules:

1. Edit: modules/{name}/index.ts
2. Type-check: npm run check
3. Build: ./build.sh (auto-compiles TypeScript)
4. Test: npm run test:modules

Code Style

The codebase follows strict conventions. Review these before submitting code:

No external dependencies. The browser bundle contains only vanilla JS and optional WASM. No React, no jQuery, no lodash, no npm packages at runtime.

Semantic HTML. Use <dialog> for modals, <details> for collapsibles, <output> for live regions, hidden attribute for visibility. Reach for a native HTML element before writing JS.

Classless CSS. Target elements by ID, semantic tag, or data-* attribute. Use classes only for: state toggles (.active, .collapsed), dynamic JS components (.council-member-row), and utility shorthands (.f1, .sc).

/* Good: semantic selectors */
#messages > article[data-from="user"] { ... }
article menu button { ... }

/* Avoid: class-heavy selectors */
.message-container .message--user .message__actions .btn { ... }

14px minimum font size. All text must be at least 14px. This ensures readability for vision LLMs that interact with the UI.

VLM-friendly click targets. Interactive elements must be at least 48px in height. Toggle switches are 44x24px. This enables AI vision models to click elements by coordinate.

AIS.lazy() for new modules. All non-core modules must use the lazy hydration pattern. The factory function runs only on first access:

if (!AIS.MyModule) AIS.lazy('MyModule', function() {
  'use strict';
  // module code
  return { publicMethod };
});

Event delegation. Attach a single listener on a container element, not individual listeners on each child:

// Good: single listener with delegation
container.addEventListener('click', e => {
  const btn = e.target.closest('[data-action]');
  if (btn) handleAction(btn.dataset.action);
});

// Avoid: per-item listeners
items.forEach(item => item.addEventListener('click', handler));

Zero polling. No setInterval, no requestAnimationFrame loops for non-animation work. Use event-driven updates and the Page Visibility API.

Passive listeners. All non-cancelable event handlers use { passive: true }:

window.addEventListener('resize', onResize, { passive: true });

Worker Tests

Worker code has its own test suite:

cd worker
npm install
npm test

Python Tooling

Python is used for validation and build scripts only -- never shipped to the browser:

# Validate model registry
python3 registry/validate.py

# Validate package registry
python3 registry/validate.py packages

# Validate a manifest file
python3 registry/validate.py manifest path/to/manifest.json

# Validate a locale file
python3 registry/locale/validate_locale.py registry/locale/es.json

Pull Request Process

1. Fork the repository
2. Create a branch for your change (e.g., add-model-deepseek-v3, translate-hindi, fix-streaming-bug)
3. Make your changes following the conventions above
4. Run validation and tests:

# For registry changes
python3 registry/validate.py

# For code changes
./build.sh
npm test
./build.sh --check

# For locale changes
python3 registry/locale/validate_locale.py registry/locale/{lang}.json

5. Submit a PR to the main branch with a clear description of what changed and why

معلومات

Registry-only changes (models, packages, translations) do not require building or running the full test suite. Just run the relevant validation script.

Getting Help

• Open a GitHub issue for bugs or feature requests
• Check existing docs at doc.aiscouncil.com
• Review CLAUDE.md in the repo root for the full architectural reference