docs: update documentation

Author: evansims

Cargo.toml

@@ -20,7 +20,7 @@ path = "src/lib.rs"
 
 [dependencies]
 # Async runtime
-tokio = { version = "1", features = ["rt-multi-thread", "sync", "time"] }
+tokio = { version = "1", features = ["rt-multi-thread", "sync", "time", "macros"] }
 async-trait = "0.1"
 futures = "0.3"
 

README.md

@@ -9,6 +9,7 @@
     <p>Ergonomic, type-safe access to InferaDB's authorization and management APIs</p>
 </div>
 
+<br />
 
 [InferaDB](https://inferadb.com/) is a distributed, [Google Zanzibar](https://research.google/pubs/zanzibar-googles-consistent-global-authorization-system/)‑inspired authorization engine that replaces ad‑hoc database lookups and scattered logic with a unified, millisecond‑latency source of truth. With this SDK, you define permissions as policy‑as‑code and wire up a type‑safe client in just a few lines.
 
@@ -21,7 +22,6 @@
 ```toml
 [dependencies]
 inferadb = "0.1"
-tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
 ```
 
 ```rust
@@ -34,51 +34,19 @@ async fn main() -> Result<(), Error> {
         .credentials(ClientCredentialsConfig {
             client_id: "my_service".into(),
             private_key: Ed25519PrivateKey::from_pem_file("private-key.pem")?,
-            certificate_id: None,
         })
         .build()
         .await?;
 
     let vault = client.organization("org_...").vault("vlt_...");
 
-    // Check permission - returns Ok(false) for denial, never errors on deny
     let allowed = vault.check("user:alice", "view", "document:readme").await?;
-
-    // Guard-style API – converts denial into an AccessDenied error.
-    vault.check("user:alice", "edit", "document:readme")
-        .require()
-        .await?;
+    println!("Allowed: {allowed}");
 
     Ok(())
 }
 ```
 
-## Installation
-
-### Feature Flags
-
-| Feature      | Default | Description                            |
-| ------------ | ------- | -------------------------------------- |
-| `grpc`       | Yes     | gRPC transport (faster, streaming)     |
-| `rest`       | Yes     | REST transport (broader compatibility) |
-| `rustls`     | Yes     | Pure-Rust TLS                          |
-| `native-tls` | No      | System TLS (OpenSSL/Schannel)          |
-| `tracing`    | No      | OpenTelemetry integration              |
-| `blocking`   | No      | Sync/blocking API wrapper              |
-| `derive`     | No      | Proc macros for type-safe schemas      |
-| `wasm`       | No      | Browser/WASM support (REST only)       |
-
-### Minimal Build (REST Only)
-
-```toml
-[dependencies]
-inferadb = { version = "0.1", default-features = false, features = ["rest", "rustls"] }
-```
-
-### Minimum Supported Rust Version
-
-The MSRV is **1.88.0**. The crate targets approximately two releases behind stable; MSRV bumps are documented in the [CHANGELOG](CHANGELOG.md). Earlier compilers are not guaranteed to work.
-
 ## Design Guarantees
 
 | Guarantee                      | Description                                                                                |
@@ -213,10 +181,11 @@ See the [Testing Guide](docs/guides/testing.md) for `InMemoryClient` (full polic
 
 | Topic                                                       | Description                                       |
 | ----------------------------------------------------------- | ------------------------------------------------- |
+| [Installation](docs/guides/installation.md)                 | Feature flags, optimized builds, TLS, MSRV        |
 | [Authentication](docs/guides/authentication.md)             | Client credentials, bearer tokens, key management |
 | [Integration Patterns](docs/guides/integration-patterns.md) | Axum, Actix-web, GraphQL, gRPC middleware         |
 | [Error Handling](docs/guides/errors.md)                     | Error types, retries, graceful degradation        |
-| [Testing](docs/guides/testing.md)                           | `MockClient`, `InMemoryClient`, `TestVault`             |
+| [Testing](docs/guides/testing.md)                           | MockClient, InMemoryClient, TestVault             |
 | [Schema Design](docs/guides/schema-design.md)               | ReBAC patterns, role hierarchy, anti-patterns     |
 | [Production Checklist](docs/guides/production-checklist.md) | Deployment readiness                              |
 | [Troubleshooting](docs/troubleshooting.md)                  | Common issues and solutions                       |

docs/README.md

@@ -6,6 +6,7 @@ Supplementary documentation for the InferaDB Rust SDK. For the main README and q
 
 | Guide                                                  | Description                                            |
 | ------------------------------------------------------ | ------------------------------------------------------ |
+| [Installation](guides/installation.md)                 | Feature flags, optimized builds, TLS options, MSRV     |
 | [Authentication](guides/authentication.md)             | Client credentials, bearer tokens, key management      |
 | [Integration Patterns](guides/integration-patterns.md) | Framework integration (Axum, Actix-web, GraphQL, gRPC) |
 | [Error Handling](guides/errors.md)                     | Error types, retries, graceful degradation             |

docs/guides/installation.md

@@ -0,0 +1,82 @@
+# Installation & Configuration
+
+## Basic Installation
+
+Add inferadb to your `Cargo.toml`:
+
+```toml
+[dependencies]
+inferadb = "0.1"
+```
+
+This includes both gRPC and REST transports with pure-Rust TLS.
+
+## Feature Flags
+
+| Feature      | Default | Description                            |
+| ------------ | ------- | -------------------------------------- |
+| `grpc`       | Yes     | gRPC transport (faster, streaming)     |
+| `rest`       | Yes     | REST transport (broader compatibility) |
+| `rustls`     | Yes     | Pure-Rust TLS                          |
+| `native-tls` | No      | System TLS (OpenSSL/Schannel)          |
+| `tracing`    | No      | OpenTelemetry integration              |
+| `blocking`   | No      | Sync/blocking API wrapper              |
+| `derive`     | No      | Proc macros for type-safe schemas      |
+| `wasm`       | No      | Browser/WASM support (REST only)       |
+
+## Optimized Builds
+
+### REST Only (Smaller Binary)
+
+```toml
+[dependencies]
+inferadb = { version = "0.1", default-features = false, features = ["rest", "rustls"] }
+```
+
+### gRPC Only (Lower Latency)
+
+```toml
+[dependencies]
+inferadb = { version = "0.1", default-features = false, features = ["grpc", "rustls"] }
+```
+
+### With Tracing
+
+```toml
+[dependencies]
+inferadb = { version = "0.1", features = ["tracing"] }
+```
+
+## TLS Options
+
+### Pure-Rust TLS (Default)
+
+Uses `rustls` with Mozilla's root certificates. No system dependencies.
+
+### Native TLS
+
+Uses the system TLS library (OpenSSL on Linux, Secure Transport on macOS, Schannel on Windows):
+
+```toml
+[dependencies]
+inferadb = { version = "0.1", default-features = false, features = ["grpc", "rest", "native-tls"] }
+```
+
+## Minimum Supported Rust Version
+
+The MSRV is **1.88.0**. We target approximately two releases behind stable.
+
+- MSRV increases are documented in the [CHANGELOG](../../CHANGELOG.md)
+- The `rust-version` field in `Cargo.toml` enforces this at build time
+- Earlier compiler versions are not guaranteed to work
+
+## WASM / Browser Support
+
+For browser environments, use REST-only with the `wasm` feature:
+
+```toml
+[dependencies]
+inferadb = { version = "0.1", default-features = false, features = ["rest", "wasm"] }
+```
+
+Note: gRPC is not supported in WASM environments.