postgres-ai · NikolayS · May 16, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -113,7 +113,7 @@ That means edits to:
 - `config/pgwatch-*/metrics.yml`
 - `config/scripts/*.sh`
 
-can be picked up locally (see “Applying config changes” below).
+can be picked up locally (see "Applying config changes" below).
 
 #### 1) Choose what Postgres you want to monitor
 
@@ -290,7 +290,7 @@ Then attach:
 ### Troubleshooting
 
 - **Compose says `PGAI_TAG is required`**: set it in `.env` (see above).
-- **Host reporter can’t connect to sink-postgres**: make sure the stack is up and `sink-postgres` is bound to `127.0.0.1:55433` (it is in `docker-compose.override.yml`).
+- **Host reporter can't connect to sink-postgres**: make sure the stack is up and `sink-postgres` is bound to `127.0.0.1:55433` (it is in `docker-compose.override.yml`).
 - **Need to regenerate pgwatch sources after editing `instances.yml`**:
 
 ```bash

diff --git a/README.md b/README.md
@@ -206,49 +206,20 @@ npx postgresai checkup --json postgresql://... | claude -p "find issues and sugg
 ## Tips
 
 - **Short alias:** `npx pgai checkup` works too
-- **Can I use it without registration on console.postgres.ai?** Yes, both express checkup and full-fledged monitoring are open-source and can be used without any connection to console.postgres.ai. In instructions above, just skip `npx postgresai auth` and:
+- **Can I use it without registration on console.postgres.ai?** Yes, both express checkup and full-fledged monitoring are open-source and can be used without any connection to console.postgres.ai. In the instructions above, just skip `npx postgresai auth` and:
     - Express checkup: use `--no-upload`
-    - Full monitoring: omit --api-key`
-- **Managed version:** Express checkup finds problems. The managed version at [console.postgres.ai](https://console.postgres.ai) also explains how to fix them and provides an Issues workflow to track fixes
-## Links
-
-| | |
-|---|---|
-| **Demo** | [demo.postgres.ai](https://demo.postgres.ai) (login: `demo` / `demo`) |
-| **Docs** | [postgres.ai/docs](https://postgres.ai/docs) |
-| **Issues** | [GitLab](https://gitlab.com/postgres-ai/postgresai/-/issues) |
-| **Community** | [Postgres.FM](https://postgres.fm) · [Postgres.TV](https://postgres.tv) |
+    - Full monitoring: omit `--api-key`
+- **Managed version:** Express checkup finds problems. The managed version at [console.postgres.ai](https://console.postgres.ai) also explains how to fix them and provides an Issues workflow to track fixes.
 
----
+## Management commands
 
-<div align="center">
-
-**[PostgresAI](https://postgres.ai)** — Self-Driving Postgres
-
-## 🎯 Use cases
-
-**For developers:**
 ```bash
-postgresai mon local-install --demo
-```
-Get a complete monitoring setup with demo data in under 2 minutes.
-
-**For production:**
-```bash
-postgresai mon local-install --api-key=your_key
-# Then add your databases
-postgresai mon targets add "postgresql://user:pass@host:port/DB"
-```
-
-## 🔧 Management commands
-
-```bash
-# Instance management
-postgresai mon targets add "postgresql://user:pass@host:port/DB"
+# Target databases
+postgresai mon targets add "postgresql://user:pass@host:port/db" my-db
 postgresai mon targets list
-postgresai mon targets test my-DB
+postgresai mon targets test my-db
 
-# Service management
+# Service lifecycle
 postgresai mon status
 postgresai mon logs
 postgresai mon restart
@@ -257,7 +228,7 @@ postgresai mon restart
 postgresai mon health
 ```
 
-## 🔄 Upgrading
+## Upgrading
 
 To upgrade postgres_ai monitoring to a newer version:
 
@@ -322,7 +293,7 @@ postgresai mon health
 
 Check Grafana dashboards at http://localhost:3000 to confirm metrics are being collected.
 
-## ☸️ Kubernetes deployment
+## Kubernetes deployment
 
 Deploy postgres_ai monitoring to Kubernetes using helm:
 
@@ -372,7 +343,7 @@ This automatically:
 - Triggers GitLab CI/CD to package and publish the chart
 - Creates a GitLab release with the packaged chart
 
-## 📋 Checkup reports
+## Checkup reports
 
 postgres_ai monitoring generates automated health check reports based on [postgres-checkup](https://gitlab.com/postgres-ai/postgres-checkup). Each report has a unique check ID and title:
 
@@ -434,36 +405,34 @@ postgres_ai monitoring generates automated health check reports based on [postgr
 |----------|-------|
 | N001 | Wait events grouped by type and query |
 
-## 🌐 Access points
+## Access points
 
-After running local-install:
+After running `local-install`:
 
-- **🚀 MAIN: Grafana Dashboard**: http://localhost:3000 (login: `monitoring`; password is shown at the end of local-install)
+- **Grafana dashboard:** http://localhost:3000 (login: `monitoring`; password is shown at the end of `local-install`)
 
 Technical URLs (for advanced users):
-- **Demo DB**: postgresql://postgres:postgres@localhost:55432/target_database
-- **Monitoring**: http://localhost:58080 (PGWatch)
-- **Metrics**: http://localhost:59090 (Victoria Metrics)
 
-## 📖 Help
+- **Demo DB:** `postgresql://postgres:postgres@localhost:55432/target_database`
+- **Monitoring:** http://localhost:58080 (PGWatch)
+- **Metrics:** http://localhost:59090 (Victoria Metrics)
+
+## Help
 
 ```bash
 postgresai --help
 postgresai mon --help
 ```
 
-## 🔑 PostgresAI access token
-Get your access token at [PostgresAI](https://postgres.ai) for automated report uploads and advanced analysis.
-
-## 🛣️ Roadmap
+## Roadmap
 
 - Host stats for on-premise and managed Postgres setups
 - `pg_wait_sampling` and `pg_stat_kcache` extension support
 - Additional expert dashboards: autovacuum, checkpointer, lock analysis
 - Query plan analysis and automated recommendations
 - Enhanced AI integration capabilities
 
-## 🧪 Testing
+## Testing
 
 Python-based report generation lives under `reporter/` and now ships with a pytest suite.
 
@@ -511,27 +480,36 @@ pytest tests/reporter -m unit --cov=reporter --cov-report=html
 
 View the coverage report by opening `htmlcov/index.html` in your browser.
 
-## 🤝 Contributing
+## Contributing
+
+We welcome contributions from Postgres experts. See [CONTRIBUTING.md](CONTRIBUTING.md) for local development setup, and the [GitLab repository](https://gitlab.com/postgres-ai/postgresai) for:
 
-We welcome contributions from Postgres experts! Please check our [GitLab repository](https://gitlab.com/postgres-ai/postgresai) for:
 - Code standards and review process
 - Dashboard design principles
 - Testing requirements for monitoring components
 
-## 📄 License
+## License
 
-This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the Apache License 2.0 — see the [LICENSE](LICENSE) file for details.
+
+## About PostgresAI
+
+`postgresai` is developed by [PostgresAI](https://postgres.ai), bringing years of Postgres expertise into automated monitoring and analysis tools. We provide enterprise consulting and advanced Postgres solutions for fast-growing companies.
+
+## Links
 
-## 🏢 About PostgresAI
+| | |
+|---|---|
+| **Demo** | [demo.postgres.ai](https://demo.postgres.ai) (login: `demo` / `demo`) |
+| **Docs** | [postgres.ai/docs](https://postgres.ai/docs) |
+| **Issues** | [GitLab](https://gitlab.com/postgres-ai/postgresai/-/issues) |
+| **Community** | [Postgres.FM](https://postgres.fm) · [Postgres.TV](https://postgres.tv) |
+| **Support** | [Get support](https://postgres.ai/contact) · [Enterprise support](https://postgres.ai/consulting) |
 
-postgres_ai monitoring is developed by [PostgresAI](https://postgres.ai), bringing years of Postgres expertise into automated monitoring and analysis tools. We provide enterprise consulting and advanced Postgres solutions for fast-growing companies.
+---
 
-## 📞 Support & community
+<div align="center">
 
-- 💬 [Get support](https://postgres.ai/contact)
-- 📺 [Postgres.TV (YouTube)](https://postgres.tv)
-- 🎙️ [Postgres FM Podcast](https://postgres.fm)
-- 🐛 [Report issues](https://gitlab.com/postgres-ai/postgresai/-/issues)
-- 📧 [Enterprise support](https://postgres.ai/consulting)
+**[PostgresAI](https://postgres.ai)** — Self-Driving Postgres
 
 </div>
diff --git a/SECURITY.md b/SECURITY.md
@@ -13,14 +13,14 @@ If you discover a security vulnerability in this project, please report it to **
 
 ### When should I NOT report a vulnerability?
 
-- Your issue is not security related.
+- Your issue is not security-related.
 
-## Security Vulnerability Response
+## Security vulnerability response
 
 Each report is acknowledged and analyzed by the project maintainers and the security team within 3 working days.
 
-The reporter will be kept updated at every stage of the issue's analysis and resolution (triage → fix → release).
+The reporter is kept updated at every stage of the issue's analysis and resolution (triage → fix → release).
 
-## Public Disclosure Timing
+## Public disclosure timing
 
 A public disclosure date is negotiated by the maintainers (security@postgres.ai) and the bug submitter. We prefer to fully disclose the bug as soon as possible once user mitigation is available. It is reasonable to delay disclosure when the bug or the fix is not yet fully understood, the solution is not well-tested, or for vendor coordination. The timeframe for disclosure is from immediate (especially if it's already publicly known) to a few weeks. We expect the timeframe between a report and public disclosure to typically be in the order of 7 days.