Merge branch 'text-polish/database-lab-prose' into 'master'

Text polish: DBLab Engine READMEs and docs (grammar, clarity, SEO)

Closes #736

See merge request postgres-ai/database-lab!1168

Author: Sarumyan

.claude/commands/cve-audit.md

@@ -3,7 +3,7 @@ description: Run CVE audit across Go deps, UI deps, and Docker image. Produce a
 argument-hint: [image-ref] (default: dblab_server:local, matches `make build-image`)
 ---
 
-# CVE Audit Protocol
+# CVE audit protocol
 
 You are running a vulnerability audit for DLE. The goal is a **triage report** that a
 developer can act on — not a raw scanner dump.

CONTRIBUTING.md

@@ -55,7 +55,7 @@ This project and everyone participating in it are governed by the [Database Lab
 - If the issue is related to UI, include screenshots and animated GIFs. Please, do NOT use screenshots for console output, configs, and logs – for those, always prefer the textual form.
 - Check if you have sensitive information in the logs and configs and remove any.
 - You can submit a bug report in either [GitLab Issues](https://gitlab.com/postgres-ai/database-lab) or [GitHub Issues](https://github.com/postgres-ai/database-lab-engine) sections – both places are monitored.
-- If you believe that there is an urgency related to the reported bug, feel free to reach out to the project maintainers. Additionally, using one of [the channels described above](#tldr-i-just-have-a-question-where-to-ask-it).
+- If you believe that there is an urgency related to the reported bug, feel free to reach out to the project maintainers. You can also use one of [the channels described above](#tldr-i-just-have-a-question-where-to-ask-it).
 - If you need to report a security issue, follow instructions in ["Database Lab Engine security guidelines"](./SECURITY.md).
 
 ### Proposing enhancements
@@ -67,7 +67,7 @@ Enhancement suggestions are tracked on [GitLab](https://gitlab.com/postgres-ai/d
 
 - Use a clear and descriptive title for the issue to identify the suggestion.
 - Provide a step-by-step description of the proposed enhancement in as many details as possible.
-- Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples
+- Provide specific examples to demonstrate the steps. Include copy/pasteable snippets that you use in those examples.
 - Use Markdown to format code snippets and improve the overall look of your issues (Markdown docs: [GitLab](https://docs.gitlab.com/ee/user/markdown.html), [GitHub](https://github.github.com/gfm/)).
 - Describe the current behavior and explain which behavior you expected to see instead and why (on GitLab, you can use the issue template, which is selected by default).
 - If your proposal is related to UI, include screenshots and animated GIFs which help you demonstrate the steps or point out the part of DLE to which the suggestion is related. Please, do NOT use screenshots for console output, logs, configs.
@@ -78,16 +78,16 @@ Enhancement suggestions are tracked on [GitLab](https://gitlab.com/postgres-ai/d
 ### Your first code contribution
 We appreciate first-time contributors, and we are happy to assist you in getting started. In case of any questions, reach out to us!
 
-You find some issues that are considered as good for first-time contributors looking at [the issues with the `good-first-issue` label](https://gitlab.com/postgres-ai/database-lab/-/issues?label_name%5B%5D=good+first+issue). Assign yourself to an issue and start discussing a possible solution. It is always a good idea to discuss and collaborate before you propose an MR/PR.
+You can find issues that are considered good for first-time contributors by looking at [the issues with the `good-first-issue` label](https://gitlab.com/postgres-ai/database-lab/-/issues?label_name%5B%5D=good+first+issue). Assign yourself to an issue and start discussing a possible solution. It is always a good idea to discuss and collaborate before you propose an MR/PR.
 
 ### Translation
-We are translating `README.md`, `CONTRIBUTING.md` (this document), and other documents in the repository to various languages to make Database Lab Engine more accessible around the globe. Help in this area is always appreciated. You can start from translating the [project's README](/README.md) to your native language and save it in `./translations/README.{language}.md`. You can find examples in the [./translations](./translations) directory
+We are translating `README.md`, `CONTRIBUTING.md` (this document), and other documents in the repository to various languages to make Database Lab Engine more accessible around the globe. Help in this area is always appreciated. You can start from translating the [project's README](/README.md) to your native language and save it in `./translations/README.{language}.md`. You can find examples in the [./translations](./translations) directory.
 
 ### Roadmap
 There is [the Roadmap section](https://postgres.ai/docs/roadmap) in the docs. It contains some major items defining big goals for the development team and the DLE community. However, these items cannot be considered a strict plan, so there are no guarantees that everything from the list will be necessarily implemented.
 
 ### Merge Requests / Pull Requests
-DLE is developed on GitLab, so MRs (merge requests) there is a way to propose a contribution. GitHub PRs (pull requests) are also an option but note that eventually, the proposal will need to be moved to GitLab, so the processing time may be increased.
+DLE is developed on GitLab, so opening a merge request (MR) there is the way to propose a contribution. GitHub PRs (pull requests) are also an option but note that eventually, the proposal will need to be moved to GitLab, so the processing time may be increased.
 
 Please follow these steps to have your contribution considered by the maintainers:
 1. Follow the [styleguides](#styleguides).
@@ -180,7 +180,7 @@ The DBLab API follows RESTful principles with these key guidelines:
 - JSON for request and response bodies
 - Comprehensive documentation with examples
 
-#### API Documentation
+#### API documentation
 We use readme.io to host the API docs: https://dblab.readme.io/ and https://api.dblab.dev.
 
 When updating the API specification:
@@ -191,21 +191,21 @@ When updating the API specification:
 #### Testing with Postman and Newman
 Postman collection is generated based on the OpenAPI spec file, using [Portman](https://github.com/apideck-libraries/portman).
 
-##### Setup and Generation
+##### Setup and generation
 1. Install Portman: `npm install -g @apideck/portman`
 2. Generate Postman collection file:
    ```bash
    portman --cliOptionsFile engine/api/postman/portman-cli.json
    ```
 
-##### Test Structure Best Practices
+##### Test structure best practices
 - Arrange tests in logical flows (create, read, update, delete)
 - Use environment variables to store and pass data between requests
 - For object creation tests, capture the ID in the response to use in subsequent requests
 - Add validation tests for response status, body structure, and expected values
 - Clean up created resources at the end of test flows
 
-##### CI/CD Integration
+##### CI/CD integration
 The Postman collection is automatically run in CI/CD pipelines using Newman. For local testing:
 ```bash
 newman run engine/api/postman/dblab_api.postman_collection.json -e engine/api/postman/branching.aws.postgres.ai.postman_environment.json
@@ -226,7 +226,7 @@ At the repository root:
 
 _Note: Don't use commands for `@postgres.ai/shared` - it's a dependent package that can't be run or built directly_
 
-#### Platform UI Development
+#### Platform UI development
 1. Set up environment variables:
    ```bash
    cd ui/packages/platform
@@ -244,7 +244,7 @@ git tag ui/1.0.12
 git push origin ui/1.0.12
 ```
 
-#### Handling Vulnerabilities
+#### Handling vulnerabilities
 When addressing vulnerabilities in UI packages:
 1. Update the affected package to a newer version if available
 2. For sub-package vulnerabilities, try using [npm-force-resolutions](https://www.npmjs.com/package/npm-force-resolutions)
@@ -255,7 +255,7 @@ For code-related issues:
 2. Follow recommendations from security analysis tools
 3. Only ignore false positives when absolutely necessary
 
-#### TypeScript Migration
+#### TypeScript migration
 - `@postgres.ai/shared` and `@postgres.ai/ce` are written in TypeScript
 - `@postgres.ai/platform` is partially written in TypeScript with ongoing migration efforts
 

PROMETHEUS.md

@@ -1,4 +1,4 @@
-# Prometheus Metrics
+# Prometheus metrics
 
 DBLab Engine exposes Prometheus metrics via the `/metrics` endpoint. These metrics can be used to monitor the health and performance of the DBLab instance.
 
@@ -10,9 +10,9 @@ GET /metrics
 
 The endpoint is publicly accessible (no authentication required) and returns metrics in Prometheus text format.
 
-## Available Metrics
+## Available metrics
 
-### Instance Metrics
+### Instance metrics
 
 | Metric Name | Type | Labels | Description |
 |-------------|------|--------|-------------|
@@ -21,7 +21,7 @@ The endpoint is publicly accessible (no authentication required) and returns met
 | `dblab_instance_status_code` | Gauge | - | Status code of the DBLab instance (0=OK, 1=Warning, 2=Bad) |
 | `dblab_retrieval_status` | Gauge | `mode`, `status` | Status of data retrieval (1=active for status) |
 
-### Disk/Pool Metrics
+### Disk/pool metrics
 
 | Metric Name | Type | Labels | Description |
 |-------------|------|--------|-------------|
@@ -34,7 +34,7 @@ The endpoint is publicly accessible (no authentication required) and returns met
 | `dblab_disk_compress_ratio` | Gauge | `pool` | Compression ratio of the filesystem (ZFS) |
 | `dblab_pool_status` | Gauge | `pool`, `mode`, `status` | Status of the pool (1=active for status) |
 
-### Clone Metrics (Aggregate)
+### Clone metrics (aggregate)
 
 | Metric Name | Type | Labels | Description |
 |-------------|------|--------|-------------|
@@ -49,7 +49,7 @@ The endpoint is publicly accessible (no authentication required) and returns met
 | `dblab_clone_total_memory_limit_bytes` | Gauge | - | Total memory limit in bytes across all clone containers |
 | `dblab_clone_protected_count` | Gauge | - | Number of protected clones |
 
-### Snapshot Metrics (Aggregate)
+### Snapshot metrics (aggregate)
 
 | Metric Name | Type | Labels | Description |
 |-------------|------|--------|-------------|
@@ -61,20 +61,20 @@ The endpoint is publicly accessible (no authentication required) and returns met
 | `dblab_snapshot_max_data_lag_seconds` | Gauge | - | Maximum data lag of any snapshot in seconds |
 | `dblab_snapshot_total_num_clones` | Gauge | - | Total number of clones across all snapshots |
 
-### Branch Metrics
+### Branch metrics
 
 | Metric Name | Type | Labels | Description |
 |-------------|------|--------|-------------|
 | `dblab_branches_total` | Gauge | - | Total number of branches |
 
-### Dataset Metrics
+### Dataset metrics
 
 | Metric Name | Type | Labels | Description |
 |-------------|------|--------|-------------|
 | `dblab_datasets_total` | Gauge | `pool` | Total number of datasets (slots) in the pool |
 | `dblab_datasets_available` | Gauge | `pool` | Number of available (non-busy) dataset slots for reuse |
 
-### Sync Instance Metrics (Physical Mode)
+### Sync instance metrics (physical mode)
 
 These metrics are only available when DBLab is running in physical mode with a sync instance enabled. They track the WAL replay status of the sync instance.
 
@@ -85,7 +85,7 @@ These metrics are only available when DBLab is running in physical mode with a s
 | `dblab_sync_uptime_seconds` | Gauge | - | Uptime of the sync instance in seconds |
 | `dblab_sync_last_replayed_timestamp` | Gauge | - | Unix timestamp of the last replayed transaction |
 
-### Observability Metrics
+### Observability metrics
 
 These metrics help monitor the health of the metrics collection system itself.
 
@@ -95,7 +95,7 @@ These metrics help monitor the health of the metrics collection system itself.
 | `dblab_scrape_duration_seconds` | Gauge | - | Duration of last metrics collection in seconds |
 | `dblab_scrape_errors_total` | Counter | - | Total number of errors during metrics collection |
 
-## Prometheus Configuration
+## Prometheus configuration
 
 Add the following to your `prometheus.yml`:
 
@@ -107,71 +107,71 @@ scrape_configs:
     metrics_path: /metrics
 ```
 
-## Example Queries
+## Example queries
 
-### Free Disk Space Percentage
+### Free disk space percentage
 
 ```promql
 100 * dblab_disk_free_bytes / dblab_disk_total_bytes
 ```
 
-### Number of Active Clones
+### Number of active clones
 
 ```promql
 dblab_clones_total
 ```
 
-### Maximum Clone Age in Hours
+### Maximum clone age in hours
 
 ```promql
 dblab_clone_max_age_seconds / 3600
 ```
 
-### Data Freshness (lag from current time)
+### Data freshness (lag from current time)
 
 ```promql
 dblab_snapshot_max_data_lag_seconds / 60
 ```
 
-### Total Memory Usage Across All Clones
+### Total memory usage across all clones
 
 ```promql
 dblab_clone_total_memory_usage_bytes
 ```
 
-### Average CPU Usage Across All Clones
+### Average CPU usage across all clones
 
 ```promql
 dblab_clone_avg_cpu_usage_percent
 ```
 
-### Clones by Status
+### Clones by status
 
 ```promql
 dblab_clones_by_status
 ```
 
-### Metrics Collection Health
+### Metrics collection health
 
 ```promql
 time() - dblab_scrape_success_timestamp
 ```
 
-### WAL Replay Lag (Physical Mode)
+### WAL replay lag (physical mode)
 
 ```promql
 dblab_sync_wal_lag_seconds
 ```
 
-### Time Since Last Replayed Transaction
+### Time since last replayed transaction
 
 ```promql
 time() - dblab_sync_last_replayed_timestamp
 ```
 
-## Alerting Examples
+## Alerting examples
 
-### Low Disk Space Alert
+### Low disk space alert
 
 ```yaml
 - alert: DBLabLowDiskSpace
@@ -184,7 +184,7 @@ time() - dblab_sync_last_replayed_timestamp
     description: "DBLab pool {{ $labels.pool }} has less than 20% free disk space"
 ```
 
-### Stale Snapshot Alert
+### Stale snapshot alert
 
 ```yaml
 - alert: DBLabStaleSnapshot
@@ -197,7 +197,7 @@ time() - dblab_sync_last_replayed_timestamp
     description: "DBLab snapshot data is more than 24 hours old"
 ```
 
-### High Clone Count Alert
+### High clone count alert
 
 ```yaml
 - alert: DBLabHighCloneCount
@@ -210,7 +210,7 @@ time() - dblab_sync_last_replayed_timestamp
     description: "DBLab has {{ $value }} clones running"
 ```
 
-### Metrics Collection Stale Alert
+### Metrics collection stale alert
 
 ```yaml
 - alert: DBLabMetricsStale
@@ -223,7 +223,7 @@ time() - dblab_sync_last_replayed_timestamp
     description: "DBLab metrics have not been updated for more than 5 minutes"
 ```
 
-### High WAL Replay Lag Alert (Physical Mode)
+### High WAL replay lag alert (physical mode)
 
 ```yaml
 - alert: DBLabHighWALLag
@@ -236,7 +236,7 @@ time() - dblab_sync_last_replayed_timestamp
     description: "DBLab sync instance WAL replay is {{ $value | humanizeDuration }} behind"
 ```
 
-### Sync Instance Down Alert (Physical Mode)
+### Sync instance down alert (physical mode)
 
 ```yaml
 - alert: DBLabSyncDown
@@ -249,11 +249,11 @@ time() - dblab_sync_last_replayed_timestamp
     description: "DBLab sync instance is not healthy"
 ```
 
-## OpenTelemetry Integration
+## OpenTelemetry integration
 
 DBLab metrics can be exported to OpenTelemetry-compatible backends using the OpenTelemetry Collector. This allows you to send metrics to Grafana Cloud, Datadog, New Relic, and other observability platforms.
 
-### Quick Start
+### Quick start
 
 1. Install the OpenTelemetry Collector:
    ```bash
@@ -292,7 +292,7 @@ DBLab metrics can be exported to OpenTelemetry-compatible backends using the Ope
                                                                      └─────────────┘
 ```
 
-### Supported Backends
+### Supported backends
 
 The OTel Collector can export to:
 - **Grafana Cloud** - Use OTLP exporter with Grafana Cloud endpoint

README.md

@@ -190,7 +190,7 @@ You can find more in the ["How-to guides" section](https://postgres.ai/docs/how-
 ## License
 The DBLab source code is licensed under the OSI-approved open source license [Apache 2.0](https://opensource.org/license/apache-2-0/).
 
-Reach out to the Postgres.ai team if you want a trial or commercial license that does not contain the GPL clauses: [Contact page](https://postgres.ai/contact).
+Reach out to the PostgresAI team if you want a trial or commercial license that does not contain the GPL clauses: [Contact page](https://postgres.ai/contact).
 
 ## Community & Support
 - [Database Lab Engine Community Covenant Code of Conduct](./CODE_OF_CONDUCT.md)

SECURITY.md

@@ -1,27 +1,27 @@
-# Database Lab Engine security guidelines
+# DBLab Engine security guidelines
 
 ## Reporting vulnerabilities
-We're extremely grateful for security researchers and users that report vulnerabilities directly to Postgres.ai and the Database Lab Engine Community. All reports are thoroughly investigated by a set of community volunteers and the Postgres.ai team.
+We're extremely grateful for security researchers and users that report vulnerabilities directly to PostgresAI and the DBLab Engine community. All reports are thoroughly investigated by a set of community volunteers and the PostgresAI team.
 
 To report a security issue, please email us at security@postgres.ai with all the details, attaching all necessary information.
 
 ### When should I report a vulnerability?
-- You think you have discovered a potential security vulnerability in the Database Lab Engine or related components.
-- You are unsure how a vulnerability affects the Database Lab Engine.
-- You think you discovered a vulnerability in another project that Database Lab Engine depends on (e.g., ZFS, Docker, etc).
-- You want to report any other security risk that could potentially harm Database Lab Engine users.
+- You think you have discovered a potential security vulnerability in DBLab Engine or related components.
+- You are unsure how a vulnerability affects DBLab Engine.
+- You think you discovered a vulnerability in another project that DBLab Engine depends on (e.g., ZFS, Docker, etc.).
+- You want to report any other security risk that could potentially harm DBLab Engine users.
 
 ### When should I NOT report a vulnerability?
-- You're helping tune Database Lab Engine for security, perform some planned experiments coordinated with the maintainers.
+- You're helping tune DBLab Engine for security, perform some planned experiments coordinated with the maintainers.
 - Your issue is not security related.
 
-## Security Vulnerability Response
+## Security vulnerability response
 Each report is acknowledged and analyzed by the project's 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).
 
-## Public Disclosure Timing
-A public disclosure date is negotiated by the Postgres.ai security team 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 time-frame between a report to public disclosure to typically be in the order of 7 days. The Database Lab Engine maintainers and the security team will take the final call on setting a disclosure date.
+## Public disclosure timing
+A public disclosure date is negotiated by the PostgresAI security team 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 time-frame between a report to public disclosure to typically be in the order of 7 days. The DBLab Engine maintainers and the security team will take the final call on setting a disclosure date.
 
 ## Known unfixed vulnerabilities
 Some third-party CVEs cannot yet be patched in DBLab Engine for reasons outside of the project's control (no upstream fix released, major-version migration required, or embedded in base-image internals). They are tracked here and resolved as upstream fixes become available.