docs: fix 25 documentation issues found by dual-verification review

Correct blocking issues across 15 documentation files:
- Fix TLS example TOML field names to match serde model (certificate_path/private_key_path)
- Fix incorrect passwords in Go test README and DEVELOPMENT.md
- Fix broken relative links in how-to guide and message-flow SVG references
- Fix CHANGELOG Prometheus metric name (cache_hit → cache_hits)
- Add missing Prometheus metrics to reference table
- Fix supported architectures to include both arm64 and amd64
- Fix LICENSE link, port convention typo, callout syntax
- Fix searchable-json operator direction, malformed JSON, and remove duplicate section
- Add .env.proxy.docker credential template to README getting-started
- Fill in "Running Proxy locally" TODO section
- Clarify cipher_cache_size, mapping_errors_enabled env var, and language test paths
- Update ARCHITECTURE.md package tree with missing directories

Author: tobyhede

ARCHITECTURE.md

@@ -214,7 +214,11 @@ packages/
 │       │   ├── parser.rs        # SQL parsing entry point
 │       │   └── context/         # Session state (statements, portals, metadata)
 │       ├── proxy/               # Encryption service, schema management, config
-│       └── config/              # Configuration parsing
+│       ├── config/              # Configuration parsing
+│       ├── cli/                 # CLI argument parsing
+│       ├── connect/             # Database connection management
+│       ├── tls/                 # TLS configuration and setup
+│       └── log/                 # Logging targets and configuration
 ├── eql-mapper/                  # SQL type inference and transformation
 │   └── src/
 │       ├── inference/           # Type inference engine

CHANGELOG.md

@@ -17,7 +17,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
-- **Cipher cache miss metric**: New Prometheus counter `cipherstash_proxy_keyset_cipher_cache_miss_total` tracks cache misses requiring cipher initialization. This complements the `cipherstash_proxy_keyset_cipher_cache_hit_total` metric, and can be used to calculate cache hit/miss ratio.
+- **Cipher cache miss metric**: New Prometheus counter `cipherstash_proxy_keyset_cipher_cache_miss_total` tracks cache misses requiring cipher initialization. This complements the `cipherstash_proxy_keyset_cipher_cache_hits_total` metric, and can be used to calculate cache hit/miss ratio.
 - **Cipher init duration metric**: New Prometheus histogram `cipherstash_proxy_keyset_cipher_init_duration_seconds` tracks cipher initialization time including ZeroKMS network calls.
 - **Encrypt/decrypt timing**: Debug logs for `encrypt_eql` and `decrypt_eql` now include `duration_ms`.
 - **Cache eviction logging**: ScopedCipher cache eviction events are now logged under the `ZEROKMS` target.

CLAUDE.md

@@ -29,6 +29,8 @@ Key capabilities:
 
 **Integration Tests (`packages/cipherstash-proxy-integration/`):**
 - Comprehensive test suite covering encryption scenarios
+
+**Language Integration Tests (`tests/python/`, `tests/integration/golang/`):**
 - Language-specific integration tests (Python, Go)
 
 **Showcase (`packages/showcase/`):**

CONTRIBUTING.md

@@ -38,4 +38,4 @@ For more information see the [Code of Conduct FAQ](./CODE_OF_CONDUCT.md) or cont
 
 ## Licensing
 
-See the [LICENSE](./LICENSE) file for our project's licensing.
+See the [LICENSE](./LICENSE.md) file for our project's licensing.

DEVELOPMENT.md

@@ -427,7 +427,7 @@ To use a different version of EQL, set the path to the desired EQL release file
 
 PostgreSQL port numbers are 4 digits:
 
-- The first two digits denote non-TLS (`55`) or non-TLS (`56`)
+- The first two digits denote non-TLS (`55`) or TLS (`56`)
 - The last two digits denote the version of PostgreSQL
 
 PostgreSQL latest always runs on `5532`.
@@ -470,7 +470,7 @@ All containers use the same credentials and database, defined in `tests/pg/commo
 POSTGRES_DB="cipherstash"
 POSTGRES_USER="cipherstash"
 PGUSER="cipherstash"
-POSTGRES_PASSWORD="password"
+POSTGRES_PASSWORD="p@ssword"
 ```
 
 PostgreSQL configuration files live at:
@@ -496,7 +496,7 @@ Environment files:
 
 If you ever get confused about where your configuration is coming from, run `mise cfg` to get a list of config files in use.
 
-Certificates are generated by `mkcert`, and live in `tests/tls/`.
+Certificates are generated by `openssl`, and live in `tests/tls/`.
 
 
 #### Configuration: development endpoints

README.md

@@ -68,9 +68,15 @@ cd proxy
 # Sign up, create a workspace, and generate credentials
 # Visit: https://dashboard.cipherstash.com/sign-up
 
-# Put credentials in .env.proxy.docker
-# Copy the credentials from the dashboard and paste them into .env.proxy.docker using your preferred text editor.
-nano .env.proxy.docker
+# Create .env.proxy.docker with your CipherStash credentials
+# Replace the placeholder values with your actual credentials from the dashboard
+cat > .env.proxy.docker << 'EOF'
+CS_WORKSPACE_CRN=crn:...your-workspace-crn...
+CS_CLIENT_ACCESS_KEY=your-client-access-key
+CS_ENCRYPT__DEFAULT_KEYSET_ID=your-keyset-id
+CS_ENCRYPT__CLIENT_ID=your-client-id
+CS_ENCRYPT__CLIENT_KEY=your-client-key
+EOF
 
 # Start the containers
 docker compose up

cipherstash-proxy-example.toml

@@ -1,14 +1,13 @@
 [tls]
-type = "Path"                         # To provide paths to PEM files
-certificate = "tests/tls/server.cert"
-private_key = "tests/tls/server.key"
+certificate_path = "tests/tls/server.cert"
+private_key_path = "tests/tls/server.key"
 
-# type = "Pem" # To directly provide PEM contents
-# certificate = """-----BEGIN CERTIFICATE-----
+# To directly provide PEM contents:
+# certificate_pem = """-----BEGIN CERTIFICATE-----
 # ...your certificate content here...
 # -----END CERTIFICATE-----
 # """
-# private_key = """-----BEGIN PRIVATE KEY-----
+# private_key_pem = """-----BEGIN PRIVATE KEY-----
 # ...your private key content here...
 # -----END PRIVATE KEY-----
 # """

docs/errors.md

@@ -220,6 +220,8 @@ When `mapping_errors_enabled` is `false` (the default), then type check errors a
 
 When `mapping_errors_enabled` is `true`, then type check errors are raised, and statement execution halts.
 
+Configure this setting with the environment variable `CS_DEVELOPMENT__ENABLE_MAPPING_ERRORS` or in the TOML config file under `[development] enable_mapping_errors = true`.
+
 In our experience, most production systems have a relatively small number of columns that require protection.
 As SQL is large and complex, instead of blocking statements with type check errors that are false negatives, the default behaviour of Proxy is to allow the statement.
 

docs/how-to/index.md

@@ -58,7 +58,7 @@ services:
 ```
 
 
-For a fully-working example, go to [`docker-compose.yml`](./docker-compose.yml).
+For a fully-working example, go to [`docker-compose.yml`](../../docker-compose.yml).
 Follow the steps in [Getting started](../README.md#getting-started) to see it in action.
 
 Once you have set up a `docker-compose.yml`, start the Proxy container:
@@ -132,7 +132,27 @@ Read the full list of configuration options and what they do in the [reference d
 
 ## Running Proxy locally
 
-TODO: Add instructions for running Proxy locally
+To run CipherStash Proxy locally for development:
+
+```bash
+# Install prerequisites
+mise trust --yes && mise install
+
+# Start PostgreSQL and install EQL
+mise run postgres:up --extra-args "--detach --wait"
+mise run postgres:setup
+
+# Run Proxy as a local process
+mise run proxy
+```
+
+Alternatively, run Proxy in a container:
+
+```bash
+mise run proxy:up --extra-args "--detach --wait"
+```
+
+See [Configuring Proxy](#configuring-proxy) for required environment variables and configuration options.
 
 ## Setting up the database schema
 
@@ -223,14 +243,14 @@ The first SQL statement adds a `match` index, which is used for partial matches
 The second SQL statement adds an `ore` index, which is used for ordering with `ORDER BY`.
 
 
-> ![IMPORTANT]
+> [!IMPORTANT]
 > Adding, updating, or deleting encrypted indexes on columns that already contain encrypted data will not re-index that data. To use the new indexes, you must `SELECT` the data out of the column, and `UPDATE` it again.
 
 To learn how to use encrypted indexes for other encrypted data types like `text`, `int`, `boolean`, `date`, and `jsonb`, see the [EQL documentation](https://github.com/cipherstash/encrypt-query-language/blob/main/docs/reference/INDEX.md).
 
 When deploying CipherStash Proxy into production environments with real data, we recommend that you apply these database schema changes with the normal tools and process you use for making changes to your database schema.
 
-To see more examples of how to modify your database schema, check out [the example schema](./sql/schema-example.sql) from [Getting started](#getting-started).
+To see more examples of how to modify your database schema, check out [the example schema](../sql/schema-example.sql) from [Getting started](#getting-started).
 
 ## Encrypting data in an existing database
 

docs/reference/index.md

@@ -16,7 +16,7 @@ This page contains reference documentation for configuring CipherStash Proxy and
 
 ## Proxy config options
 
-You can configure CipherStash Proxy with a config file, enviroment variables, or a combination of the two – see [Configuring Proxy](#configuring-proxy) for instructions.
+You can configure CipherStash Proxy with a config file, environment variables, or a combination of the two – see [Configuring Proxy](#configuring-proxy) for instructions.
 
 The following are all the configuration options available for Proxy, with their equivalent environment variables:
 
@@ -29,7 +29,7 @@ The following are all the configuration options available for Proxy, with their
 # Env: CS_SERVER__HOST
 host = "0.0.0.0"
 
-# Proxy host posgt
+# Proxy host port
 # Optional
 # Default: `6432`
 # Env: CS_SERVER__PORT
@@ -60,8 +60,8 @@ worker_threads = "4"
 # Env: CS_SERVER__THREAD_STACK_SIZE
 thread_stack_size = "2097152"
 
-# Cipher cache size (number of entries)
-# Sets the maximum number of encryption/decryption operations to cache
+# Cipher cache size (number of keyset-scoped ciphers)
+# Sets the maximum number of keyset-scoped ciphers to cache (internal sizing is calculated per entry)
 # Optional
 # Default: `64`
 # Env: CS_SERVER__CIPHER_CACHE_SIZE
@@ -82,7 +82,7 @@ cipher_cache_ttl_seconds = "3600"
 # Env: CS_DATABASE__HOST
 host = "0.0.0.0"
 
-# Database host post
+# Database host port
 # Optional
 # Default: `5432`
 # Env: CS_DATABASE__PORT
@@ -199,7 +199,7 @@ format = "pretty"
 # Log format
 # Optional
 # Valid values: `stdout | stderr`
-# Default: `info`
+# Default: `stdout`
 # Env: CS_LOG__OUTPUT
 output = "stdout"
 
@@ -238,7 +238,7 @@ slow_db_response_min_duration_ms = "100"
 # Env: CS_PROMETHEUS__ENABLED
 enabled = "false"
 
-# Prometheus exporter post
+# Prometheus exporter port
 # Optional
 # Default: `9930`
 # Env: CS_PROMETHEUS__PORT
@@ -562,6 +562,8 @@ If the proxy is running on a host other than localhost, access on that host.
 | `cipherstash_proxy_statements_session_duration_seconds_sum`     | Count     | Total time CipherStash Proxy spent processing SQL statements                |
 | `cipherstash_proxy_statements_encrypted_total`                  | Counter   | Number of SQL statements that required encryption                           |
 | `cipherstash_proxy_statements_passthrough_total`                | Counter   | Number of SQL statements that did not require encryption                    |
+| `cipherstash_proxy_statements_passthrough_mapping_disabled_total` | Counter   | Number of SQL statements passed through because mapping was disabled        |
+| `cipherstash_proxy_slow_statements_total`                         | Counter   | Number of SQL statements that exceeded the slow statement threshold         |
 | `cipherstash_proxy_statements_total`                            | Counter   | Total number of SQL statements processed by CipherStash Proxy               |
 | `cipherstash_proxy_statements_unmappable_total`                 | Counter   | Total number of unmappable SQL statements processed by CipherStash Proxy    |
 
@@ -629,9 +631,9 @@ rate(cipherstash_proxy_keyset_cipher_cache_hits_total[5m])
 
 ## Supported architectures
 
-CipherStash Proxy is [available as a Docker container image](https://hub.docker.com/r/cipherstash/proxy) for `linux/arm64` architectures.
+CipherStash Proxy is [available as a Docker container image](https://hub.docker.com/r/cipherstash/proxy) for `linux/arm64` and `linux/amd64` architectures.
 
-If you're interested in a Docker image for other architectures (like `linux/amd64`), upvote [this idea](https://github.com/cipherstash/proxy/discussions/214).
+For other architecture requests, see [this discussion](https://github.com/cipherstash/proxy/discussions/214).