> ## Documentation Index
> Fetch the complete documentation index at: https://gigi-f9937525.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> How developers can contribute safely to GigiDC.

# Contributing

GigiDC is being rebuilt in small, reviewable slices. Contributions should keep shipped behavior, roadmap intent, and documentation in sync.

## Contribution Rules

* Keep pull requests focused and reviewable.
* Always use the repository pull request template in `.github/pull_request_template.md` when opening a PR. Fill the existing sections instead of replacing the template with an ad-hoc summary.
* When code behavior, commands, config, environment variables, migrations, deployment, Discord behavior, permissions, plugin behavior, or setup steps change, update the matching Mintlify docs in `docs/`.
* Keep docs aligned with code truth. Do not document planned behavior as shipped behavior.
* If a docs page is added, removed, renamed, or moved, update `docs/docs.json` navigation in the same pull request.
* Update architecture docs when runtime boundaries, storage, permissions, memory, LLM, or external app integration behavior changes.
* Attribute external resources, libraries, APIs, examples, generated assets, and source material in docs or the relevant deliverable.
* Review code, docs, configs, logs, tests, fixtures, and generated output for secrets or private Discord content before commit.
* For observability docs such as agent stats, traces, LLM usage, memory counts, and audit views, state whether output is aggregate, actor-scoped, or per-record, and never imply raw prompts, memory snippets, provider payloads, tool arguments, secrets, or private Discord content are exposed.
* Use `internal/evalharness` for repeatable agent golden cases that need response, audit, durable-step, confirmation, or redaction assertions without a live Discord, database, or provider.
* Keep agent artifacts only in ignored local `.agents/`.
* Do not track superpowers artifacts, agent plans, agent reports, scratch notes, private planning files, local harnesses, tokens, `.env` files, or raw exported private data.
* Before commit, verify docs commands, paths, environment variables, examples, and migration notes against the current repository state.

## Plugin Manifest Contributions

Future plugin work can include contributed `gigi-plugin.json` manifests for known external Discord bots, private guild tools, or external services Gigi may drive through Discord.

These manifests are contribution material, not automatic discovery. A manifest can only become useful after maintainer review and guild-admin approval through the plugin install flow.

Each manifest must keep the same format as Gigi's runtime validator:

* `id`, `name`, `version`, `source`, and `source_kind`
* exact `discord_application_id` or `discord_bot_user_id`
* optional `manifest_url` when source kind is `manifest_url`
* `capabilities` with name and description
* `actions` with id, trigger, surfaces, safety class, optional permissions, optional dispatch, optional adapter, and optional `arg_schema`
* legacy top-level `triggers`, `surfaces`, `permissions`, and `dispatch` are accepted, but new contributions should use `actions`
* top-level `surfaces`
* optional top-level `permissions` only for legacy manifests
* optional top-level `dispatch` only for legacy manifests
* optional `config_schema`
* `audit_events`
* `attribution` with name, use, and source

Contribution rules for manifests:

* Use exact Discord application ID or bot user ID; do not rely on bot display names, role names, domains, or fuzzy matches.
* Declare only behavior verified from public docs, maintainer-owned source, or direct admin-owned configuration.
* Keep action trigger `value` as the exact external app command Gigi should send. Use `aliases` only for alternate text Gigi may accept from a user mention.
* Do not include secrets, provider keys, private URLs, private Discord messages, private guild data, or hidden prompts.
* Do not scrape private content or submit LLM-guessed behavior as fact.
* Use action-level `dispatch: "send_message"` only for public prefix actions that are safe to send as Gigi; otherwise omit it or use `dry_run`.
* Include attribution for Discord docs, external app docs, provider docs, and any examples used to build the manifest.
* Keep one plugin manifest contribution per PR unless multiple manifests share one small schema fix.
* Use `source_kind: "uploaded_file"` only for manifests imported from Discord attachments; URL imports are normalized to `manifest_url`.

Discord application IDs, bot user IDs, and application command behavior are based on Discord's public developer documentation: [Discord Developer Documentation](https://discord.com/developers/docs).

## Current Limits

Gigi can validate and store approved manifests, dispatch public `send_message` prefix actions when a guild enables an approved manifest version with stored public-dispatch consent, and use configured semantic routing to propose validated dry-run plans. Restricted dispatch, richer command surfaces, and LLM-driven dispatch are still future work. Contributor manifests prepare that catalog one known external app at a time.

Do not document an external app integration as usable until the runtime can import, enable, authorize, audit, and drive that external app behavior.