type-bridge 1.4.0.dev0__tar.gz → 1.4.2__tar.gz

{type_bridge-1.4.0.dev0 → type_bridge-1.4.2}/.github/workflows/ci.yml

@@ -18,6 +18,11 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
 
@@ -44,6 +49,45 @@ jobs:
         working-directory: type-bridge-core
         run: cargo clippy --all-targets -- -D warnings
 
+  # Rust code coverage (informational, does not block CI)
+  rust-coverage:
+    name: Rust Coverage
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Rust nightly
+        uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: llvm-tools-preview
+
+      - name: Install cargo-llvm-cov
+        uses: taiki-e/install-action@cargo-llvm-cov
+
+      - name: Cache cargo registry and build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            type-bridge-core/target
+          key: ${{ runner.os }}-cargo-nightly-${{ hashFiles('type-bridge-core/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-nightly-
+
+      - name: Generate LCOV report
+        run: ./scripts/coverage.sh branch --lcov
+
+      - name: Upload Rust coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: type-bridge-core/target/llvm-cov/lcov.branch.info
+          flags: rust
+          fail_ci_if_error: false
+
   # Build maturin wheels for all platforms (parallel with other jobs)
   build-wheels:
     name: Build wheel (${{ matrix.target }})
@@ -194,8 +238,21 @@ jobs:
       - name: Install pytest-xdist for parallel execution
         run: uv pip install pytest-xdist
 
-      - name: Run unit tests in parallel
-        run: uv run pytest tests/unit/ -v --tb=short -n auto
+      - name: Run unit tests with coverage
+        run: |
+          uv run pytest tests/unit/ -v --tb=short -n auto \
+            --cov=type_bridge --cov-branch \
+            --cov-report=xml:coverage.xml \
+            --cov-report=term-missing
+
+      - name: Upload Python coverage to Codecov
+        uses: codecov/codecov-action@v5
+        if: always()
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          flags: python
+          fail_ci_if_error: false
 
   # Integration tests (require TypeDB server, parallel by test category)
   test-integration:

type_bridge-1.4.2/.github/workflows/docs.yml

@@ -0,0 +1,86 @@
+name: Documentation
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - "type_bridge/**"
+      - "mkdocs.yml"
+      - "scripts/gen_ref_pages.py"
+  pull_request:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - "type_bridge/**"
+      - "mkdocs.yml"
+      - "scripts/gen_ref_pages.py"
+  workflow_dispatch:
+
+# Allow only one concurrent deployment
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
+# Sets permissions for GitHub Pages deployment
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo registry and build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            type-bridge-core/target
+          key: ${{ runner.os }}-cargo-docs-${{ hashFiles('type-bridge-core/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-docs-
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra docs
+
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+
+      - name: Upload artifact
+        if: github.ref == 'refs/heads/master' && github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.ref == 'refs/heads/master' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

{type_bridge-1.4.0.dev0 → type_bridge-1.4.2}/.github/workflows/release.yml

@@ -45,6 +45,52 @@ jobs:
       - name: Run unit tests
         run: uv run pytest tests/unit/ -v --tb=short
 
+  # Publish Rust crates to crates.io (dependency order)
+  publish-crates:
+    name: Publish Rust crates to crates.io
+    needs: test
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Publish type-bridge-core-lib
+        working-directory: type-bridge-core
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: cargo publish -p type-bridge-core-lib || true
+
+      - name: Wait for crates.io index
+        run: sleep 30
+
+      - name: Publish type-bridge-orm-derive
+        working-directory: type-bridge-core
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: cargo publish -p type-bridge-orm-derive || true
+
+      - name: Wait for crates.io index
+        run: sleep 30
+
+      - name: Publish type-bridge-orm
+        working-directory: type-bridge-core
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: cargo publish -p type-bridge-orm || true
+
+      - name: Wait for crates.io index
+        run: sleep 30
+
+      - name: Publish type-bridge-server
+        working-directory: type-bridge-core
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: cargo publish -p type-bridge-server || true
+
   # Build type-bridge-core wheels for all platforms
   build-core-wheels:
     name: Build core wheel (${{ matrix.target }})
@@ -178,6 +224,8 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
 
   # Publish type-bridge to PyPI (after core is available)
   publish-python-pypi:
@@ -196,11 +244,13 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
 
   # Create draft GitHub Release with all artifacts
   github-release:
     name: Create GitHub Release
-    needs: publish-python-pypi
+    needs: [publish-python-pypi, publish-crates]
     runs-on: ubuntu-latest
     permissions:
       contents: write

{type_bridge-1.4.0.dev0 → type_bridge-1.4.2}/.gitignore

@@ -22,10 +22,20 @@ packages/typescript/dist/
 # Coverage
 .coverage
 htmlcov/
+coverage.xml
 
 # Temporary
 tmp/
 
+# Benchmarks
+benchmarks/.results/
+.benchmarks/
+
+# MkDocs build output
+site/
+
 # Reference repos
 typeql-ref/
-type-bridge-core/target/
+type-bridge-core/**/target/
+*.profraw
+*.profdata

{type_bridge-1.4.0.dev0 → type_bridge-1.4.2}/CHANGELOG.md

@@ -2,6 +2,127 @@
 
 All notable changes to TypeBridge will be documented in this file.
 
+## [Unreleased]
+
+## [1.4.2] - 2026-03-04
+
+##### Rust Server — `type-bridge-server`
+- **`CrudInfo`** on `RequestContext` — operation, type_name, type_kind, attribute_names, iid
+- **`CrudInterceptor` trait** with `on_crud_request` / `on_crud_response` and `should_intercept`
+- **`CrudInterceptorAdapter`** bridges `CrudInterceptor` into the existing `Interceptor` chain
+
+## [1.4.1] - 2026-03-03
+
+### New Features
+
+#### Lifecycle Hook System (PR #118, closes #116)
+
+Three-layer hook system for reacting to CRUD lifecycle events (audit logging, validation, cache invalidation, async notifications).
+
+##### Python ORM — `type_bridge.crud.hooks`
+- **`CrudEvent` enum** — `PRE_INSERT`, `POST_INSERT`, `PRE_UPDATE`, `POST_UPDATE`, `PRE_DELETE`, `POST_DELETE`, `PRE_PUT`, `POST_PUT`
+- **`LifecycleHook` protocol** — implement only the methods you need (`pre_insert`, `post_delete`, etc.)
+- **`HookCancelled` exception** — raise in a pre-hook to abort the operation
+- **Per-manager registration** — `manager.add_hook(hook)` / `manager.remove_hook(hook)`, chainable
+- **`should_run(event, sender)`** filtering by event type or model class
+- Pre-hooks run in registration order; post-hooks run in reverse order (middleware unwinding)
+- Zero overhead when no hooks are registered
+
+##### Rust ORM — `type-bridge-orm`
+- **`LifecycleHook` trait** with `HookContext`, `PreHookResult` (Continue/Reject), and `HookRunner`
+- Integrated into `EntityManager` and `RelationManager` via `add_hook()`
+- Same semantics as the Python layer (registration-order pre-hooks, reverse-order post-hooks)
+
+#### Put (Upsert) Clause — `type-bridge-core-lib`
+- **Added `Clause::Put(Vec<Statement>)` variant** for idempotent insert (upsert) operations
+  - Parser: `parse_put_clause` with keyword lookahead in both `parse_patterns` and `parse_statements`
+  - Compiler: Generates `put\n<statements>;` TypeQL output
+  - Validation: Reuses Insert validation rules (`Clause::Insert | Clause::Put`)
+  - Full roundtrip support (parse → AST → compile → parse)
+
+### Refactoring
+
+#### Server API Simplification — `type-bridge-server`
+- **Removed standalone CRUD module** (`/entities/*`, `/relations/*` endpoints, `CrudQueryBuilder`, raw query support) — superseded by the interceptor-based design
+- **Removed `crud_builder` benchmark** and `criterion` dev-dependency
+- **Server now has 4 endpoints**: `POST /query`, `POST /query/validate`, `GET /health`, `GET /schema`
+
+## [1.4.0] - 2026-02-20
+
+### Highlights
+
+- 5 new Rust crates: `core-lib`, `orm`, `orm-derive`, `server`, and `python` (PyO3 bindings)
+- Up to **40x faster validation** and **2.5x faster query compilation** via the Rust backend
+- Async Rust ORM with derive macros, chainable queries, and batch operations
+- Query-intercepting proxy server with REST endpoints
+- MkDocs Material documentation site
+
+### New Features
+
+#### Rust Core — `type-bridge-core-lib` (PRs #95, #101-#108)
+- **TypeQL schema parser** with inheritance resolution and PyO3 bindings
+- **TypeQL query parser** with bidirectional AST roundtrip
+- **Schema-aware query validation** with statement and pattern validators
+- **Rust-backed value coercion** and `format_value`
+- **Custom validation rules** with portable JSON DSL
+- **Wired Rust core into Python** compiler and validation pipeline
+
+#### Async Rust ORM — `type-bridge-orm` (PR #114)
+- **Async ORM** with entity CRUD and mock-testable session layer
+- **Derive macros** — `#[derive(TypeBridgeEntity)]`, `#[derive(TypeBridgeRelation)]`, `#[derive(TypeBridgeAttribute)]`
+- **Chainable query builders** with expression filtering and aggregation
+- **Schema management** — registration, generation, diff, and sync
+- **Abstract types** with inheritance and code generation
+- **Batch operations** — `insert_many`, `delete_many`, `update_many`
+- **`FieldRef<A>`** for type-safe query field references
+- **`include_schema!`** proc-macro for compile-time TQL codegen
+- **Schema introspection** from live TypeDB database
+- **Group-by queries** with `GroupByResult`
+- **Role player field access** for relation query filtering
+- **Expression helpers** — `in_range()`, `startswith()`, `endswith()`
+- **Connection pooling** with `Database::into_shared()`
+- **Serde support** on all ORM model types
+- **Structured tracing** spans on all public methods
+
+#### Query Intercept Proxy — `type-bridge-server` (PR #109)
+- **REST CRUD endpoints** with schema-aware query building
+- **`CrudQueryBuilder` PyO3 class** for TypeQL generation from Python
+- **Extensible library/framework** — pluggable `QueryExecutor`, `Interceptor`, `SchemaSource`
+- **207 tests** with 100% MC/DC coverage
+
+### Performance: Python vs Rust
+
+#### Validation
+
+| Operation | Python | Rust | Speedup |
+|-----------|--------|------|---------|
+| Single type name | 1.89 us | 354.75 ns | **5.3x** |
+| Long name (100+ chars) | 24.90 us | 620.52 ns | **40.1x** |
+| Batch 1,000 names | 5.32 ms | 266.80 us | **19.9x** |
+| Batch 5,000 names | 28.02 ms | 1.33 ms | **21.1x** |
+
+#### Query Compilation (via serde bridge)
+
+| Operation | Python | Rust | Speedup |
+|-----------|--------|------|---------|
+| Standalone update | 93.28 us | 37.82 us | **2.5x** |
+| Large batch (200 clauses) | 2.26 ms | 1.07 ms | **2.1x** |
+| Heavy insert (100x6) | 1.71 ms | 896.19 us | **1.9x** |
+
+### Documentation & CI
+
+- **MkDocs + Material** documentation site with auto-generated API reference (PR #98)
+- **Rust crate CI** with multi-platform wheel builds — Linux (x86_64, aarch64), macOS (x86_64, aarch64), Windows (x86_64) (PR #95)
+- **Comprehensive benchmark suite** with TOML storage, comparison reports, and markdown generation (PR #103)
+- **Codecov integration** for Rust coverage tracking (PR #109)
+
+### Bug Fixes
+
+- Resolve Rust 1.93.0 clippy lint errors
+- Pin Python 3.13 for Rust CI jobs and fix coverage script
+- Add version specifiers to inter-crate path dependencies for crates.io publishing
+- Make release workflow idempotent (skip already-published packages)
+
 ## [1.3.0] - 2026-02-09
 
 ### New Features

{type_bridge-1.4.0.dev0 → type_bridge-1.4.2}/CLAUDE.md

@@ -84,6 +84,7 @@ type_bridge/
 │   ├── base.py           # Type variables (E, R)
 │   ├── utils.py          # Shared utilities (format_value, is_multi_value_attribute)
 │   ├── exceptions.py     # CRUD exceptions
+│   ├── hooks.py          # Lifecycle hooks (CrudEvent, HookCancelled, CrudHook, HookRunner)
 │   ├── entity/           # Entity CRUD operations
 │   │   ├── __init__.py   # Entity module exports
 │   │   ├── manager.py    # EntityManager class
@@ -187,37 +188,39 @@ The project requires:
 
 ## Documentation
 
+Full documentation site: **[https://ds1sqe.github.io/type-bridge/](https://ds1sqe.github.io/type-bridge/)**
+
 ### User Documentation
 
 - **[README.md](README.md)** - Quick start guide for users
 
 ### Development Guides
 
-- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development setup, commands, code quality standards
-- **[docs/TESTING.md](docs/TESTING.md)** - Testing strategy, patterns, and execution
+- **[docs/development/setup.md](docs/development/setup.md)** - Development setup, commands, code quality standards
+- **[docs/development/testing.md](docs/development/testing.md)** - Testing strategy, patterns, and execution
 
 ### TypeDB Integration
 
-- **[docs/TYPEDB.md](docs/TYPEDB.md)** - TypeDB concepts, driver API, TypeQL syntax, 3.x changes
-- **[docs/ABSTRACT_TYPES.md](docs/ABSTRACT_TYPES.md)** - Abstract types and interface hierarchies in TypeDB
+- **[docs/development/typedb.md](docs/development/typedb.md)** - TypeDB concepts, driver API, TypeQL syntax, 3.x changes
+- **[docs/development/abstract-types.md](docs/development/abstract-types.md)** - Abstract types and interface hierarchies in TypeDB
 
 ### Architecture & Internals
 
-- **[docs/INTERNALS.md](docs/INTERNALS.md)** - Internal type system, ModelAttrInfo, modern Python standards
-
-### API Reference
-
-- **[docs/api/README.md](docs/api/README.md)** - API overview and quick reference
-- **[docs/api/attributes.md](docs/api/attributes.md)** - Attribute types and value types
-- **[docs/api/entities.md](docs/api/entities.md)** - Entity definition and ownership
-- **[docs/api/relations.md](docs/api/relations.md)** - Relations, roles, and role players
-- **[docs/api/abstract_types.md](docs/api/abstract_types.md)** - Abstract types implementation and patterns
-- **[docs/api/cardinality.md](docs/api/cardinality.md)** - Card API and Flag system
-- **[docs/api/crud.md](docs/api/crud.md)** - CRUD operations and managers
-- **[docs/api/queries.md](docs/api/queries.md)** - Query expressions and aggregations
-- **[docs/api/schema.md](docs/api/schema.md)** - Schema management and conflict detection
-- **[docs/api/generator.md](docs/api/generator.md)** - Code generator (TQL → Python)
-- **[docs/api/validation.md](docs/api/validation.md)** - Pydantic integration and type safety
+- **[docs/development/internals.md](docs/development/internals.md)** - Internal type system, ModelAttrInfo, modern Python standards
+
+### User Guide (API docs)
+
+- **[docs/guide/index.md](docs/guide/index.md)** - API overview and quick reference
+- **[docs/guide/attributes.md](docs/guide/attributes.md)** - Attribute types and value types
+- **[docs/guide/entities.md](docs/guide/entities.md)** - Entity definition and ownership
+- **[docs/guide/relations.md](docs/guide/relations.md)** - Relations, roles, and role players
+- **[docs/guide/abstract-types.md](docs/guide/abstract-types.md)** - Abstract types implementation and patterns
+- **[docs/guide/cardinality.md](docs/guide/cardinality.md)** - Card API and Flag system
+- **[docs/guide/crud.md](docs/guide/crud.md)** - CRUD operations and managers
+- **[docs/guide/queries.md](docs/guide/queries.md)** - Query expressions and aggregations
+- **[docs/guide/schema.md](docs/guide/schema.md)** - Schema management and conflict detection
+- **[docs/guide/generator.md](docs/guide/generator.md)** - Code generator (TQL → Python)
+- **[docs/guide/validation.md](docs/guide/validation.md)** - Pydantic integration and type safety
 
 ## Getting Help
 

{type_bridge-1.4.0.dev0 → type_bridge-1.4.2}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: type-bridge
-Version: 1.4.0.dev0
+Version: 1.4.2
 Summary: A modern, Pythonic ORM for TypeDB with an Attribute-based API
 Project-URL: Homepage, https://github.com/ds1sqe/type-bridge
 Project-URL: Repository, https://github.com/ds1sqe/type-bridge
-Project-URL: Documentation, https://github.com/ds1sqe/type-bridge/blob/master/README.md
+Project-URL: Documentation, https://ds1sqe.github.io/type-bridge/
 Project-URL: Issues, https://github.com/ds1sqe/type-bridge/issues
 Author-email: ds1sqe <ds1sqe@mensakorea.org>
 License: MIT
@@ -22,16 +22,24 @@ Requires-Dist: isodate==0.7.2
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: lark>=1.1.9
 Requires-Dist: pydantic>=2.12.4
-Requires-Dist: type-bridge-core>=0.1.0.dev0
+Requires-Dist: type-bridge-core>=1.4.2
 Requires-Dist: typedb-driver>=3.8.0
 Requires-Dist: typer>=0.15.0
 Provides-Extra: dev
 Requires-Dist: pyright>=1.1.407; extra == 'dev'
 Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-benchmark>=5.1.0; extra == 'dev'
 Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
 Requires-Dist: pytest-order>=1.2.0; extra == 'dev'
 Requires-Dist: pytest>=9.0.1; extra == 'dev'
 Requires-Dist: ruff>=0.14.5; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-gen-files>=0.5; extra == 'docs'
+Requires-Dist: mkdocs-literate-nav>=0.6; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs-section-index>=0.3; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
 Description-Content-Type: text/markdown
 
 # TypeBridge
@@ -61,6 +69,7 @@ A modern, Pythonic ORM for [TypeDB](https://github.com/typedb/typedb) with an At
 - **Data Validation**: Automatic type checking and coercion via Pydantic, including keyword validation
 - **JSON Support**: Seamless JSON serialization/deserialization
 - **CRUD Operations**: Full CRUD with fetching API (get, filter, all, update) for entities and relations
+- **Lifecycle Hooks**: Pre/post-operation hooks for audit logging, validation, cache invalidation, and async notifications
 - **Chainable Operations**: Filter, delete, and bulk update with method chaining and lambda functions
 - **Query Builder**: Pythonic interface for building TypeQL queries
 - **Multi-player Roles**: A single role can accept multiple entity types via `Role.multi(...)`
@@ -72,18 +81,19 @@ A modern, Pythonic ORM for [TypeDB](https://github.com/typedb/typedb) with an At
 ## Installation
 
 ```bash
-# Clone the repository
-git clone https://github.com/ds1sqe/type-bridge.git
-cd type_bridge
+# Install from PyPI
+pip install type-bridge
 
-# Install with uv
-uv sync
+# Or with uv
+uv add type-bridge
+```
 
-# Or with pip
-pip install -e .
+**From source:**
 
-# Or add to project with uv
-uv add type-bridge
+```bash
+git clone https://github.com/ds1sqe/type-bridge.git
+cd type_bridge
+uv sync
 ```
 
 ## Quick Start
@@ -292,31 +302,16 @@ The generator supports:
 - Registry module generation for schema metadata and JSON Schema fragments
 - Both `#` and `//` comment styles
 
-See [docs/api/generator.md](docs/api/generator.md) for full documentation.
+See the [Code Generator guide](https://ds1sqe.github.io/type-bridge/guide/generator/) for full documentation.
 
 ## Documentation
 
-- **[CLAUDE.md](CLAUDE.md)** - Project guidance for development, TypeDB concepts, and quick reference
-- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development setup, commands, and code quality standards
-- **[docs/TESTING.md](docs/TESTING.md)** - Testing strategy, patterns, and execution
-- **[docs/TYPEDB.md](docs/TYPEDB.md)** - TypeDB concepts, driver API, and TypeQL syntax
-- **[docs/ABSTRACT_TYPES.md](docs/ABSTRACT_TYPES.md)** - Abstract types and interface hierarchies in TypeDB
-- **[docs/INTERNALS.md](docs/INTERNALS.md)** - Internal type system and architecture
-- **[docs/SKILL.md](docs/SKILL.md)** - AI assistant skill for using type-bridge (for Claude, GPT, etc.)
-
-### API Reference
-
-- **[docs/api/README.md](docs/api/README.md)** - API overview and quick reference
-- **[docs/api/attributes.md](docs/api/attributes.md)** - Attribute types and value types
-- **[docs/api/entities.md](docs/api/entities.md)** - Entity definition and ownership
-- **[docs/api/relations.md](docs/api/relations.md)** - Relations, roles, and role players
-- **[docs/api/abstract_types.md](docs/api/abstract_types.md)** - Abstract types implementation and patterns
-- **[docs/api/cardinality.md](docs/api/cardinality.md)** - Card API and Flag system
-- **[docs/api/crud.md](docs/api/crud.md)** - CRUD operations and managers
-- **[docs/api/queries.md](docs/api/queries.md)** - Query expressions and aggregations
-- **[docs/api/schema.md](docs/api/schema.md)** - Schema management and conflict detection
-- **[docs/api/generator.md](docs/api/generator.md)** - Code generator (TQL → Python)
-- **[docs/api/validation.md](docs/api/validation.md)** - Pydantic integration and type safety
+**[https://ds1sqe.github.io/type-bridge/](https://ds1sqe.github.io/type-bridge/)** — Full documentation site with user guide, API reference, and development guides.
+
+- [Getting Started](https://ds1sqe.github.io/type-bridge/getting-started/) — Installation and quick start
+- [User Guide](https://ds1sqe.github.io/type-bridge/guide/) — Attributes, entities, relations, CRUD, queries, and more
+- [API Reference](https://ds1sqe.github.io/type-bridge/reference/) — Auto-generated from source docstrings
+- [Development](https://ds1sqe.github.io/type-bridge/development/) — Setup, testing, and internals
 
 ## Pydantic Integration
 
@@ -374,7 +369,7 @@ TypeBridge uses a two-tier testing approach with **100% test pass rate**:
 
 ```bash
 # Unit tests (fast, no external dependencies) - DEFAULT
-uv run pytest                              # Run unit tests (0.3s)
+uv run pytest                              # Run unit tests
 uv run pytest tests/unit/attributes/ -v   # Test all 9 attribute types
 uv run pytest tests/unit/core/ -v         # Test core functionality
 uv run pytest tests/unit/flags/ -v        # Test flag system
@@ -399,11 +394,31 @@ uv run pytest -m "" -v                    # Run all tests
 ./check.sh                                # Run linting and type checking
 ```
 
+## Rust Core
+
+The project includes a Rust core (`type-bridge-core/`) that provides high-performance implementations of the query compiler, validation engine, and value coercer. When the native extension is installed, Python automatically delegates to Rust for:
+
+- **Validation** — up to 40x faster schema-aware query validation
+- **Compilation** — up to 2.5x faster AST-to-TypeQL compilation via serde bridge
+- **Value coercion** — Type-safe value coercion and TypeQL literal formatting
+
+The Rust core is a Cargo workspace with five crates:
+
+| Crate | Description |
+|-------|-------------|
+| `type-bridge-core-lib` | Pure-Rust AST, schema parser, query compiler, and validation engine |
+| `type-bridge-orm` | Async ORM with entity/relation managers, chainable queries, and batch operations |
+| `type-bridge-orm-derive` | Derive macros for `TypeBridgeEntity`, `TypeBridgeRelation`, `TypeBridgeAttribute` |
+| `type-bridge-core` | PyO3 bindings exposing the Rust core to Python |
+| `type-bridge-server` | Transport-agnostic query pipeline with interceptor chain and HTTP API |
+
+See [`type-bridge-core/README.md`](type-bridge-core/README.md) for build instructions and architecture details.
+
 ## Requirements
 
 - Python 3.13+
-- TypeDB 3.7.0-rc0 server (fully compatible)
-- typedb-driver>=3.7.0
+- TypeDB 3.x server
+- typedb-driver>=3.8.0
 - pydantic>=2.12.4
 - isodate==0.7.2 (for Duration type support)
 - lark>=1.1.9 (for schema parsing)