chore: improve docs and add AGENTS.md

[ogonkov]

Summary by Sourcery

Generate README from Handlebars templates and align CLI help/docs with the actual flag schema, while adding internal guidance for contributors and tightening tooling around TypeScript and markdown imports.

Enhancements:

• Add a Handlebars-based script to generate README.md from templates and CLI help metadata.
• Extend the custom Node module loader to support importing markdown files as ES modules and to type-check JavaScript via tsconfig checkJs.
• Clarify source layout, parameter combinations, and runtime behavior buckets for different scaffold configurations across the project.

Build:

• Wire a generate-readme npm script into package.json to regenerate README.md from templates before distribution.

Documentation:

• Document CLI flags, usage examples, generated project layouts, and Node version requirements in a generated README.
• Add AGENTS.md and SKILL documentation to describe project architecture, testing conventions, generator templates, and e2e coverage.
• Introduce CLAUDE.md to point AI assistants at AGENTS.md for repo-specific guidance.

Tests:

• Add a node:test suite for the README generator to ensure README.md matches the generated output.

[sourcery-ai]

Reviewer's Guide

Automates README generation from CLI metadata, extends the custom Node ESM loader to support Markdown imports and JS type-checking, and adds internal documentation (AGENTS/CLAUDE skills) plus a regression test to keep README in sync.

File-Level Changes

Change	Details	Files
Introduce Handlebars-based README generation from CLI help/package metadata and wire it into tooling.	Add scripts/generate-readme.ts that builds Handlebars context from buildHelpData() and package.json engines and renders readme.hbs/flagsTable.hbs to stdout. Create scripts/readme/readme.hbs and flagsTable.hbs templates that define README structure, flags table, examples, generated project layout, and Node requirements. Update README.md to be a generated file with a header warning and content driven by the template (flags, examples, project shapes, Node version). Add an npm script generate-readme that runs the TS loader and generate-readme.ts, redirecting output to README.md. Add scripts/generate-readme.test.ts to exec the generator and assert README.md matches its output using Markdown-as-text import.	scripts/generate-readme.ts scripts/readme/readme.hbs scripts/readme/flagsTable.hbs README.md package.json scripts/generate-readme.test.ts
Extend Node ESM loader and TS config to support importing Markdown as text and type-check JS helper files.	Change scripts/ts-extension-override.js to use typed ResolveHook and add a LoadHook that reads .md files and returns an ES module exporting the file contents as default. Add scripts/md.d.ts to declare '*.md' modules as string content for TypeScript. Enable checkJs in tsconfig.json to type-check JavaScript files used in loader/helpers.	scripts/ts-extension-override.js scripts/md.d.ts tsconfig.json
Add internal guidance docs for contributors and AI agents, including repo architecture, testing, templates, and e2e behaviors.	Add AGENTS.md describing CLI purpose, source layout, checks, conventions, parameter matrix, and generated project structure. Add e2e/AGENTS.md documenting Playwright e2e setup, targeting, runtime-observable config buckets, and coverage gaps. Add src/generators/templates/AGENTS.md documenting template-related gotchas and eslint/node env considerations. Add .claude/skills/writing-unit-tests/SKILL.md with detailed guidance on unit-test style, mocking patterns, and common mistakes. Add CLAUDE.md pointing at AGENTS.md as the main entrypoint for AI agents. Introduce .gitattributes (content not shown in diff, likely for attributes like generated files or text normalization).	AGENTS.md e2e/AGENTS.md src/generators/templates/AGENTS.md .claude/skills/writing-unit-tests/SKILL.md CLAUDE.md .gitattributes

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}