docs: improve repository SEO and discoverability

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug Report
+about: Report a bug in ymsdk
+title: "[Bug] "
+labels: bug
+assignees: ''
+---
+
+## Description
+
+A clear description of the bug.
+
+## Steps to Reproduce
+
+1. 
+2. 
+3. 
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened.
+
+## Environment
+
+- Go version: 
+- ymsdk version: 
+- OS: 
+
+## Code Sample
+
+```go
+// Minimal code to reproduce the issue
+```
+
+## Additional Context
+
+Any other context, error messages, or stack traces.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Documentation
+    url: https://pkg.go.dev/github.com/rekurt/ymsdk
+    about: Check the Go package documentation

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,29 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: "[Feature] "
+labels: enhancement
+assignees: ''
+---
+
+## Problem
+
+What problem does this feature solve?
+
+## Proposed Solution
+
+Describe the feature you'd like to see.
+
+## Alternatives Considered
+
+Any alternative approaches you've considered.
+
+## API Design (optional)
+
+```go
+// How you imagine the API would look
+```
+
+## Additional Context
+
+Any other context or examples.

.github/pull_request_template.md

@@ -0,0 +1,17 @@
+## Summary
+
+Brief description of changes.
+
+## Changes
+
+- 
+
+## Testing
+
+- [ ] `go test ./...` passes
+- [ ] `golangci-lint run` passes
+- [ ] New tests added for new functionality
+
+## Related Issues
+
+Closes #

CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery and unwelcome sexual attention
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening an issue or contacting the maintainers.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing to ymsdk
+
+[Русская версия](#как-внести-вклад-в-ymsdk)
+
+Thank you for your interest in contributing to ymsdk! This document provides guidelines for contributing.
+
+## Getting Started
+
+1. Fork and clone the repository
+2. Install Go 1.25+ and [golangci-lint](https://golangci-lint.run/)
+3. Run tests: `go test ./...`
+4. Run linter: `golangci-lint run --config .golangci.yml`
+
+## Development Workflow
+
+1. Create a feature branch from `master`
+2. Make your changes with tests
+3. Ensure all tests pass and linter is clean
+4. Submit a pull request
+
+## Code Standards
+
+- Follow existing code patterns and architecture
+- All public APIs must have doc comments
+- Table-driven tests are preferred
+- Use `internal/testutil.FakeDoer` for HTTP mocking in tests
+- Line length limit: 180 characters
+- Import order: stdlib → external → `github.com/rekurt/` packages
+
+## Pull Request Guidelines
+
+- Keep PRs focused on a single change
+- Include tests for new functionality
+- Update documentation if adding public API
+- Reference related issues in the PR description
+
+## Reporting Issues
+
+Use GitHub Issues with the provided templates for bug reports and feature requests.
+
+---
+
+# Как внести вклад в ymsdk
+
+Спасибо за интерес к проекту! Ниже описаны правила для контрибьюторов.
+
+## Начало работы
+
+1. Форкните и клонируйте репозиторий
+2. Установите Go 1.25+ и [golangci-lint](https://golangci-lint.run/)
+3. Запустите тесты: `go test ./...`
+4. Запустите линтер: `golangci-lint run --config .golangci.yml`
+
+## Рабочий процесс
+
+1. Создайте feature-ветку от `master`
+2. Внесите изменения с тестами
+3. Убедитесь, что тесты проходят и линтер чист
+4. Отправьте pull request
+
+## Стандарты кода
+
+- Следуйте существующим паттернам и архитектуре
+- Все публичные API должны иметь doc-комментарии
+- Предпочтительны table-driven тесты
+- Используйте `internal/testutil.FakeDoer` для мокирования HTTP в тестах
+- Ограничение длины строки: 180 символов
+- Порядок импортов: stdlib → external → `github.com/rekurt/`
+
+## Правила Pull Request
+
+- PR должен быть сфокусирован на одном изменении
+- Включайте тесты для новой функциональности
+- Обновляйте документацию при добавлении публичного API
+- Ссылайтесь на связанные issues в описании PR
+
+## Сообщения об ошибках
+
+Используйте GitHub Issues с предоставленными шаблонами для баг-репортов и запросов функциональности.

README.en.md

@@ -2,8 +2,25 @@
 
 [Русская версия](README.md)
 
+[![CI](https://github.com/rekurt/ymsdk/actions/workflows/ci.yml/badge.svg)](https://github.com/rekurt/ymsdk/actions/workflows/ci.yml)
+[![Go Reference](https://pkg.go.dev/badge/github.com/rekurt/ymsdk.svg)](https://pkg.go.dev/github.com/rekurt/ymsdk)
+[![Go Report Card](https://goreportcard.com/badge/github.com/rekurt/ymsdk)](https://goreportcard.com/report/github.com/rekurt/ymsdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Go Version](https://img.shields.io/github/go-mod/go-version/rekurt/ymsdk)](go.mod)
+
 Lightweight Go client for Yandex Messenger Bot API with typed models, built-in retry, and services for core API methods. Docs: https://pkg.go.dev/github.com/rekurt/ymsdk
 
+## Features
+
+- **Type-safe models** — `ChatID`, `UserLogin`, `MessageID` and other distinct types prevent mix-ups at compile time
+- **Automatic retry** — exponential backoff with configurable retry strategy
+- **Rate limit handling** — automatic respect for API `Retry-After` headers
+- **Service-oriented architecture** — separate packages for messages, chats, polls, updates, files, and users
+- **Polling & Webhooks** — two update delivery modes
+- **Debug logging** — structured logs via `zap` with HTTP request/response inspection
+- **Minimal dependencies** — only `go.uber.org/zap`
+- **Full API coverage** — all core Yandex Messenger Bot API methods
+
 ## Installation
 
 ```bash

README.md

@@ -2,8 +2,25 @@
 
 [English](README.en.md)
 
+[![CI](https://github.com/rekurt/ymsdk/actions/workflows/ci.yml/badge.svg)](https://github.com/rekurt/ymsdk/actions/workflows/ci.yml)
+[![Go Reference](https://pkg.go.dev/badge/github.com/rekurt/ymsdk.svg)](https://pkg.go.dev/github.com/rekurt/ymsdk)
+[![Go Report Card](https://goreportcard.com/badge/github.com/rekurt/ymsdk)](https://goreportcard.com/report/github.com/rekurt/ymsdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Go Version](https://img.shields.io/github/go-mod/go-version/rekurt/ymsdk)](go.mod)
+
 Легковесный Go-клиент для Yandex Messenger Bot API с типобезопасными моделями, встроенным retry и сервисами для всех основных методов API. Документация: https://pkg.go.dev/github.com/rekurt/ymsdk
 
+## Возможности
+
+- **Типобезопасные модели** — `ChatID`, `UserLogin`, `MessageID` и другие типы предотвращают ошибки на этапе компиляции
+- **Автоматический retry** — экспоненциальный backoff с настраиваемой стратегией повторных попыток
+- **Rate limit** — автоматическое соблюдение `Retry-After` заголовков API
+- **Сервис-ориентированная архитектура** — отдельные пакеты для сообщений, чатов, опросов, обновлений, файлов и пользователей
+- **Polling и Webhooks** — два режима получения обновлений
+- **Debug-логирование** — структурированные логи через `zap` с HTTP-инспекцией
+- **Минимум зависимостей** — только `go.uber.org/zap`
+- **Полное покрытие API** — все основные методы Yandex Messenger Bot API
+
 ## Установка
 
 ```bash

SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| latest  | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in ymsdk, please report it responsibly.
+
+**Do NOT open a public GitHub issue for security vulnerabilities.**
+
+Instead, please report vulnerabilities by opening a
+[private security advisory](https://github.com/rekurt/ymsdk/security/advisories/new)
+on GitHub.
+
+You should receive a response within 48 hours. We will work with you to
+understand the issue and address it promptly.
+
+## Security Considerations
+
+This SDK handles API tokens for the Yandex Messenger Bot API. Please ensure:
+
+- Never commit API tokens to version control
+- Use environment variables or secret management for token storage
+- Keep the SDK updated to the latest version
+- Review the `ymerrors` package for proper error handling of authentication failures

client/doc.go

@@ -0,0 +1,16 @@
+// Package client provides the [YMClient] aggregator — a single entry point
+// to all Yandex Messenger Bot API services.
+//
+// Create a client with [New] and access services through its fields:
+//
+//	cs := client.New(ym.Config{Token: os.Getenv("YM_TOKEN")})
+//	msg, _ := cs.Messages.SendToChat(ctx, chatID, "hello", nil)
+//	chat, _ := cs.Chats.Create(ctx, &chats.ChatCreateRequest{...})
+//	updates, _ := cs.Updates.Get(ctx, 100, "")
+//
+// If you need a pre-configured core [ym.Client] (e.g. with custom HTTP
+// transport), use [Wrap] instead:
+//
+//	cl := ym.NewClientWithHTTP(cfg, customHTTP)
+//	cs := client.Wrap(cl)
+package client

client/ym/chats/doc.go

@@ -0,0 +1,14 @@
+// Package chats provides operations for creating and managing chats and
+// channels in Yandex Messenger.
+//
+// The service supports creating group chats and channels, as well as
+// updating chat membership (adding and removing members).
+//
+// Create the service via [NewService] with a configured [ym.Client]:
+//
+//	svc := chats.NewService(ymClient)
+//	chat, err := svc.Create(ctx, &chats.ChatCreateRequest{
+//	    Name:    "Team Chat",
+//	    Members: []ym.ChatMember{{Login: "alice"}},
+//	})
+package chats

client/ym/files/doc.go

@@ -0,0 +1,12 @@
+// Package files provides operations for uploading files to Yandex Messenger
+// chats.
+//
+// Files can be sent to a chat by [ym.ChatID] or directly to a user by
+// [ym.UserLogin]. The service handles multipart form encoding and
+// automatic retry on transient failures.
+//
+// Create the service via [NewService] with a configured [ym.Client]:
+//
+//	svc := files.NewService(ymClient)
+//	msg, err := svc.SendToChat(ctx, chatID, "report.pdf", fileReader)
+package files

client/ym/messages/doc.go

@@ -0,0 +1,15 @@
+// Package messages provides operations for sending, deleting, and managing
+// messages in Yandex Messenger chats.
+//
+// The service supports plain-text messages, file and image attachments,
+// image galleries, and message deletion. Messages can be sent to a chat
+// by [ym.ChatID] or directly to a user by [ym.UserLogin].
+//
+// Create the service via [NewService] with a configured [ym.Client]:
+//
+//	svc := messages.NewService(ymClient)
+//	msg, err := svc.SendToChat(ctx, chatID, "Hello!", nil)
+//
+// File operations include uploading files and images, sending multi-image
+// galleries, and downloading files by ID.
+package messages

client/ym/polls/doc.go

@@ -0,0 +1,19 @@
+// Package polls provides operations for creating and managing polls in
+// Yandex Messenger chats.
+//
+// The service supports poll creation, retrieving poll results, and
+// paginating through individual voter responses.
+//
+// Create the service via [NewService] with a configured [ym.Client]:
+//
+//	svc := polls.NewService(ymClient)
+//	msg, err := svc.Create(ctx, &polls.CreatePollRequest{
+//	    ChatID:   chatID,
+//	    Question: "Lunch?",
+//	    Answers:  []string{"Pizza", "Sushi"},
+//	})
+//
+// Use [Service.GetResults] to fetch aggregated poll results and
+// [Service.GetAllVoters] to collect all individual votes with automatic
+// pagination.
+package polls

client/ym/self/doc.go

@@ -0,0 +1,10 @@
+// Package self provides operations for managing the bot's own settings in
+// Yandex Messenger, such as configuring webhook URLs.
+//
+// Create the service via [NewService] with a configured [ym.Client]:
+//
+//	svc := self.NewService(ymClient)
+//	bot, err := svc.Update(ctx, &self.SelfUpdateRequest{
+//	    WebhookURL: "https://example.com/webhook",
+//	})
+package self