docs: publish AI tooling guide and migrate development docs (#2141)

Author: derberg

.coderabbit.yaml

@@ -53,10 +53,10 @@ knowledge_base:
     enabled: true
     filePatterns:
       # Add custom patterns here if you have other guideline files:
-      - "AGENT.md"
+      - "AGENTS.md"
       - ".github/pr-review-checklist.md"
-      - "Development.md"
-      - "CONTRIBUTING.md"
+      - "apps/generator/docs/release-process.md"
+      - "apps/generator/docs/contributing.md"
   learnings:
     scope: auto
   issues:

.github/pr-review-checklist.md

@@ -1,7 +1,7 @@
 ### What reviewer looks at during PR review
 The following are ideal points maintainers look for during review. Reviewing these points yourself beforehand can help streamline the review process and reduce time to merge.
 
-1. **PR Title**: Use a concise title that follows our [Conventional Commits](https://github.com/asyncapi/generator/blob/master/CONTRIBUTING.md#conventional-commits) guidelines and clearly summarizes the change using [imperative mood](https://cbea.ms/git-commit/#imperative) (it means `spoken or written as if giving a command or instruction`, like "add new helper for listing operations")
+1. **PR Title**: Use a concise title that follows our [Conventional Commits](https://www.asyncapi.com/docs/tools/generator/contributing#conventional-commits) guidelines and clearly summarizes the changes using the [imperative mood](https://cbea.ms/git-commit/#imperative) (written as if giving a command or instruction such as "add new helper for listing operations")
     > **Note** - In Generator, prepend `feat:` or `fix:` in PR title only when PATCH/MINOR release must be triggered.
 
 1. **PR Description**: Clearly explain the issue being solved, summarize the changes made, and mention the related issue.

.gitignore

@@ -20,4 +20,7 @@ __pycache__
 **/target/
 
 microcks-data
-packages/templates/clients/websocket/test/__fixtures__/bundled.yml
+packages/templates/clients/websocket/test/__fixtures__/bundled.yml
+
+# Local planning/brainstorming artifacts (not part of published docs)
+docs/superpowers/

AGENTS.md

@@ -10,8 +10,8 @@ The monorepo contains tightly coupled packages that together form the AsyncAPI c
 
 The guidelines below cross-reference the following authoritative docs. If a path or URL changes, update it here **and** at each inline mention.
 
-- [Conventional Commits](CONTRIBUTING.md#conventional-commits) — commit and PR title format rules
-- [Release process](Development.md#release-process) — changesets, release-triggering prefixes, full release flow
+- [Conventional Commits](apps/generator/docs/contributing.md#conventional-commits) — commit and PR title format rules
+- [Release process](apps/generator/docs/release-process.md) — changesets, release-triggering prefixes, full release flow
 - [Packages README](packages/README.md) — template architectural principles and assumptions
 - [Hooks guide](apps/generator/docs/hooks.md) — lifecycle hook order and signatures (`generate:before`, `generate:after`, `setFileTemplateName`)
 - [Keeper README](apps/keeper/README.md) — `@asyncapi/keeper` public API surface
@@ -51,7 +51,7 @@ Orchestration is Turborepo (`turbo.json`). Every package-level script (`test`, `
 Every package inherits the root `.eslintrc` — that file is the source of truth for lint rules. Package `lint` scripts must invoke the root config and ignore file via relative `--config` / `--ignore-path` flags — the exact number of `../` segments depends on the package's depth in the tree (e.g. `apps/*` uses `../../.eslintrc`; `packages/templates/clients/<protocol>/test/integration-test/` uses `../../../../../../.eslintrc`). Do not add a package-local `.eslintrc` to avoid the relative path.
 
 ### 2.3 Commits and PR titles
-See the [Conventional Commits section in `CONTRIBUTING.md`](CONTRIBUTING.md#conventional-commits).
+See the [Conventional Commits section in the contributing guide](apps/generator/docs/contributing.md#conventional-commits).
 
 ### 2.4 Documentation and comments
 
@@ -72,7 +72,7 @@ Required tags: `@param`, `@returns`, and `@throws` / `@async` where applicable.
 **Comments:** reserve comments for non-obvious *why*. In this codebase the comments that pay rent are **Parser-API quirks** and **AsyncAPI spec workarounds** — mark these with a `// Why:` prefix that cites the spec section or parser issue, so future cleanup passes can tell a load-bearing comment from a stale one.
 
 ### 2.5 Release hygiene
-Changesets, release-triggering prefixes, and the full release flow are documented in the [Release process section in `Development.md`](Development.md#release-process). Use that as the source of truth on review; flag PRs whose diffs suggest a release but ship no `.changeset/*.md`.
+Changesets, release-triggering prefixes, and the full release flow are documented in the [Release process documentation](apps/generator/docs/release-process.md). Use that as the source of truth on review; flag PRs whose diffs suggest a release but ship no `.changeset/*.md`.
 
 A changeset must name the **published** package a change ships through — not the directory you edited. `packages/templates/*` are `private` and unpublished, so they are **never** valid changeset targets; baked-in template changes reach users via `@asyncapi/generator`. Map changed files to the changeset package as:
 

AI-POLICY.md

@@ -1,57 +1,9 @@
 # AI Usage Policy
 
-This policy governs the use of generative AI and AI-assisted tooling (LLMs, coding agents, autocomplete assistants, and similar) when contributing to this repository.
+The full AI Usage Policy is now part of the official documentation, published at **[asyncapi.com/docs/tools/generator/ai-policy](https://www.asyncapi.com/docs/tools/generator/ai-policy)**. The source lives in [`apps/generator/docs/ai-policy.md`](apps/generator/docs/ai-policy.md). This file is a short index.
 
-> **AI tools are instruments; humans are the only authors.**
+> **AI tools are instruments — humans are the only authors.**
 
-You may use AI tools to help you contribute. But the moment you open a pull request or an issue, **you** are the author of every line in it. The tool is not a co-maintainer, it is not accountable, and it cannot be cited as an excuse. This policy exists so that AI accelerates good contributions without lowering the bar for quality, security, or trust.
+The policy covers when it applies, your responsibilities as a contributor, the required `Generated-by:` disclosure, and the consequences of non-compliance. Read it in full before submitting AI-assisted work.
 
-This is a contributor-facing policy. It is **not** the same as [`AGENTS.md`](AGENTS.md): that file instructs coding agents on *how to write code that fits this repository*, whereas this policy defines *the rules and expectations for humans who use AI to contribute here*.
-
-## When this applies
-
-This policy applies to **any** contribution where a generative AI tool materially assisted in producing the content, including:
-
-- source code, tests, and configuration,
-- documentation and template content,
-- issue descriptions, and
-- review comments.
-
-If you only used AI for spell-checking, search, or to understand existing code, disclosure is not required. If AI generated or substantially shaped the content you are submitting, it is.
-
-## Your responsibilities as a contributor
-
-Before you submit AI-assisted work, you must:
-
-1. **Review it thoroughly.** Read and understand every part of the contribution. If you do not understand it, do not submit it.
-2. **Verify quality.** Ensure it meets this project's standards — it builds, tests pass, and it follows the conventions in [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`AGENTS.md`](AGENTS.md).
-3. **Remove extraneous changes.** Strip out unrelated edits, dead code, speculative abstractions, and noise the tool introduced. Keep the diff focused.
-4. **Be prepared to explain it.** You must be able to justify any part of the contribution if a maintainer asks. "The AI wrote it" is not an answer.
-5. **Accept responsibility.** You bear full accountability for the contribution, exactly as if you had written every line by hand.
-6. **Check licensing.** Confirm that generated material does not reproduce code under incompatible licenses and does not violate this project's [license](LICENSE).
-
-> Blindly copy-pasting AI output introduces security and stability risks. Maintainers may close such pull requests without review.
-
-## Required disclosure
-
-If a contribution was materially AI-assisted, you **must** disclose it:
-
-- **Pull requests:** include a `Generated-by:` line in the PR description naming the tool and its version, for example:
-
-  ```text
-  Generated-by: Claude Code 1.x
-  Generated-by: GitHub Copilot
-  ```
-
-  The pull request template carries a dedicated AI-assistance section — fill in the `Generated-by:` line, or check the "no AI assistance" box if it does not apply. A CI check verifies that one of the two is present; it confirms a declaration exists, it does not and cannot verify its truthfulness.
-
-- **Issues:** note in the issue body that AI assisted in drafting it.
-
-Disclosure is a sign of good faith, not an admission of wrongdoing. We welcome AI-assisted contributions that follow this policy.
-
-## Consequences
-
-- Maintainers may **close non-compliant pull requests without review**, including undisclosed AI-generated PRs and PRs the contributor cannot explain.
-- **Repeated violations** are treated as a breach of our [Code of Conduct](CODE_OF_CONDUCT.md) and may result in the contributor being blocked.
-
-If you are unsure whether something falls under this policy, ask a maintainer in the `#generator` channel on [AsyncAPI Slack](https://www.asyncapi.com/slack-invite) before submitting.
+See also the [AI tooling guide](https://www.asyncapi.com/docs/tools/generator/ai-tooling) for the AI tools the project runs on your PRs and issues.