You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iceberg.apache.org by at...@apache.org on 2026/06/11 18:34:33 UTC

(iceberg-go) branch main updated: docs(website): expand site with tutorial, API recipes, and V1/V2/V3 status (#1181)

This is an automated email from the ASF dual-hosted git repository.

laskoviymishka pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-go.git


The following commit(s) were added to refs/heads/main by this push:
     new 9af9dc52 docs(website): expand site with tutorial, API recipes, and V1/V2/V3 status (#1181)
9af9dc52 is described below

commit 9af9dc524a438fd12adff6fe31d7f1127514f09c
Author: Neelesh Salian <ns...@users.noreply.github.com>
AuthorDate: Thu Jun 11 11:34:27 2026 -0700

    docs(website): expand site with tutorial, API recipes, and V1/V2/V3 status (#1181)
    
    ## Summary
    
    Restructure go.iceberg.apache.org from a 6-page feature listing into a
    complete documentation site modeled on py.iceberg.apache.org.
    
    **New pages** :
    
    - `getting-started.md` - runnable SQLite-catalog tutorial with an Arrow
    round-trip
    - `configuration.md` - YAML config, per-catalog options, S3 / GCS /
    Azure credentials, table properties, pluggability
    - `api.md` (rewritten) - recipe book for catalogs, namespaces, tables,
    scans, writes, schema and partition evolution, snapshots, maintenance,
    views, type mapping
    - `row-filter-syntax.md`, `expression-dsl.md` - predicate DSL sub-pages
    under API
    - `feature-status.md` - capability matrix and a new V1 / V2 / V3 spec
    coverage section
    - `ecosystem.md` - cross-links to Iceberg Java, PyIceberg, iceberg-rust,
    iceberg-cpp
    - `releases.md`, `verify-release.md`, `how-to-release.md` - sourced from
    `dev/release/`
    - `community.md`, `contributing.md` (mdbook-includes the root
    `CONTRIBUTING.md`)
    
    **Updated:** `introduction.md` is now a thin landing page. `SUMMARY.md`
    is rewired for the new sections.
    
    Current docs: https://go.iceberg.apache.org
    
    Updated docs look like this:
    
    <img width="1510" height="748" alt="Screenshot 2026-06-10 at 1 46 18 PM"
    src="https://github.com/user-attachments/assets/eccccd83-fd17-4aaf-befa-03a3b14aaa5b"
    />
    
    ## Test plan
    - `cd website && mdbook serve`
---
 README.md                                   |   6 +-
 website/src/SUMMARY.md                      |  17 +
 website/src/api.md                          | 764 ++++++++++++++--------------
 website/src/community.md                    |  45 ++
 website/src/configuration.md                | 336 ++++++++++++
 website/src/{SUMMARY.md => contributing.md} |  13 +-
 website/src/ecosystem.md                    |  43 ++
 website/src/expression-dsl.md               | 131 +++++
 website/src/feature-status.md               | 131 +++++
 website/src/getting-started.md              | 255 ++++++++++
 website/src/how-to-release.md               |  93 ++++
 website/src/introduction.md                 |  87 +---
 website/src/releases.md                     |  48 ++
 website/src/row-filter-syntax.md            | 143 ++++++
 website/src/verify-release.md               | 104 ++++
 15 files changed, 1750 insertions(+), 466 deletions(-)

diff --git a/README.md b/README.md
index b2357f68..ba2c4492 100644
--- a/README.md
+++ b/README.md
@@ -157,13 +157,13 @@ the table, the following tracks the current write support:
 |:---------------------|:---------:|
 | Append Stream        |     X     |
 | Append Data Files    |     X     |
-| Rewrite Files        |           |
+| Rewrite Files        |     X     |
 | Rewrite manifests    |           |
 | Overwrite Files      |     X     |
 | Copy-On-Write Delete |     X     |
 | Write Pos Delete     |     X     |
-| Write Eq Delete      |           |
-| Row Delta            |           |
+| Write Eq Delete      |     X     |
+| Row Delta            |     X     |
 
 
 ### CLI Usage
diff --git a/website/src/SUMMARY.md b/website/src/SUMMARY.md
index 7d3934c8..d43c6b97 100644
--- a/website/src/SUMMARY.md
+++ b/website/src/SUMMARY.md
@@ -22,10 +22,27 @@
 # User Guide
 
 - [Install](./install.md)
+- [Getting Started](./getting-started.md)
+- [Configuration](./configuration.md)
 - [CLI](./cli.md)
 - [API](./api.md)
+  - [Row Filter Syntax](./row-filter-syntax.md)
+  - [Expression DSL](./expression-dsl.md)
+- [Feature Status](./feature-status.md)
 
 # Developer Guide
 
+- [Contributing](./contributing.md)
+- [Community](./community.md)
 - [Glossary](./glossary.md)
 
+# Releases
+
+- [Releases](./releases.md)
+  - [Verify a release](./verify-release.md)
+  - [How to release](./how-to-release.md)
+
+# Ecosystem
+
+- [Other Iceberg implementations](./ecosystem.md)
+
diff --git a/website/src/api.md b/website/src/api.md
index 7ac9a277..7633ab99 100644
--- a/website/src/api.md
+++ b/website/src/api.md
@@ -17,556 +17,562 @@
   ~ under the License.
 -->
 
-# Catalog
+# API
 
-`Catalog` is the entry point for accessing iceberg tables. You can use a catalog to:
+The Go API surface for Apache Iceberg Go. New to the project? Walk through the [Getting Started](./getting-started.md) tutorial first - the recipes here assume you already have a catalog and a table.
 
-* Create and list namespaces.
-* Create, load, and drop tables
+For configuration knobs (catalog options, FileIO credentials, table properties), see [Configuration](./configuration.md). For predicate construction details, see [Row Filter Syntax](./row-filter-syntax.md) and [Expression DSL](./expression-dsl.md).
 
-Multiple catalog implementations are available: REST, Hive, Glue, and SQL. Here is an
-example of how to create a `RestCatalog`:
+## Catalog
+
+`catalog.Catalog` is the entry point for everything: namespaces, tables, views.
+
+### Constructing a catalog
+
+#### REST
 
 ```go
 import (
     "context"
-    "github.com/apache/iceberg-go/catalog"
+
     "github.com/apache/iceberg-go/catalog/rest"
 )
 
-// Create a REST catalog
-cat, err := rest.NewCatalog(context.Background(), "rest", "http://localhost:8181", 
+cat, err := rest.NewCatalog(context.Background(), "rest", "http://localhost:8181",
     rest.WithOAuthToken("your-token"))
-if err != nil {
-    log.Fatal(err)
-}
 ```
 
-You can run the following code to list all root namespaces:
+#### SQL (SQLite, Postgres, MySQL, Oracle, MSSQL)
 
 ```go
-// List all root namespaces
-namespaces, err := cat.ListNamespaces(context.Background(), nil)
-if err != nil {
-    log.Fatal(err)
-}
+import (
+    "database/sql"
 
-for _, ns := range namespaces {
-    fmt.Printf("Namespace: %v\n", ns)
-}
-```
+    "github.com/apache/iceberg-go"
+    sqlcat "github.com/apache/iceberg-go/catalog/sql"
+    "github.com/uptrace/bun/driver/sqliteshim"
+)
 
-Then you can run the following code to create namespace:
-```go
-// Create a namespace
-namespace := catalog.ToIdentifier("my_namespace")
-err = cat.CreateNamespace(context.Background(), namespace, nil)
-if err != nil {
-    log.Fatal(err)
-}
+db, err := sql.Open(sqliteshim.ShimName, "file:catalog.db")
+// handle err
+cat, err := sqlcat.NewCatalog("default", db, sqlcat.SQLite, iceberg.Properties{
+    "warehouse": "file:///tmp/warehouse",
+})
 ```
 
-## Other Catalog Types
-
-### SQL Catalog
-
-You can also use SQL-based catalogs:
+#### Glue
 
 ```go
 import (
-    "github.com/apache/iceberg-go/catalog"
-    "github.com/apache/iceberg-go/io"
+    "github.com/apache/iceberg-go/catalog/glue"
+    "github.com/aws/aws-sdk-go-v2/config"
 )
 
-// Create a SQLite catalog
-cat, err := catalog.Load(context.Background(), "local", iceberg.Properties{
-    "type":               "sql",
-    "uri":                "file:iceberg-catalog.db",
-    "sql.dialect":        "sqlite",
-    "sql.driver":         "sqlite",
-    io.S3Region:          "us-east-1",
-    io.S3AccessKeyID:     "admin",
-    io.S3SecretAccessKey: "password",
-    "warehouse":          "file:///tmp/warehouse",
-})
-if err != nil {
-    log.Fatal(err)
-}
+awsCfg, err := config.LoadDefaultConfig(context.TODO())
+// handle err
+cat := glue.NewCatalog(glue.WithAwsConfig(awsCfg))
 ```
 
-### Glue Catalog
-
-For AWS Glue integration:
+#### Hive
 
 ```go
 import (
-    "github.com/apache/iceberg-go/catalog/glue"
-    "github.com/aws/aws-sdk-go-v2/config"
+    "github.com/apache/iceberg-go"
+    "github.com/apache/iceberg-go/catalog/hive"
 )
 
-// Create AWS config
-awsCfg, err := config.LoadDefaultConfig(context.TODO())
-if err != nil {
-    log.Fatal(err)
-}
+cat, err := hive.NewCatalog(iceberg.Properties{},
+    hive.WithURI("thrift://localhost:9083"),
+    hive.WithWarehouse("s3://my-bucket/warehouse"))
+```
 
-// Create Glue catalog
-cat := glue.NewCatalog(glue.WithAwsConfig(awsCfg))
+#### Hadoop
 
-// Create a table in Glue
-tableIdent := catalog.ToIdentifier("my_database", "my_table")
-tbl, err := cat.CreateTable(
-    context.Background(),
-    tableIdent,
-    schema,
-    catalog.WithLocation("s3://my-bucket/tables/my_table"),
+```go
+import (
+    "github.com/apache/iceberg-go"
+    "github.com/apache/iceberg-go/catalog/hadoop"
 )
-if err != nil {
-    log.Fatal(err)
-}
-```
 
-# Table
+cat, err := hadoop.NewCatalog("default", "file:///tmp/warehouse", iceberg.Properties{})
+```
 
-After creating `Catalog`, we can manipulate tables through `Catalog`.
+#### Via the registry
 
-You can use the following code to create a table:
+`catalog.Load` looks up the right backend via the `type` property (or `uri` scheme as a fallback) plus your `~/.iceberg-go.yaml`. Useful when you want runtime selection:
 
 ```go
 import (
     "github.com/apache/iceberg-go"
     "github.com/apache/iceberg-go/catalog"
-    "github.com/apache/iceberg-go/table"
-)
-
-// Create a simple schema
-schema := iceberg.NewSchemaWithIdentifiers(1, []int{2},
-    iceberg.NestedField{ID: 1, Name: "foo", Type: iceberg.PrimitiveTypes.String, Required: false},
-    iceberg.NestedField{ID: 2, Name: "bar", Type: iceberg.PrimitiveTypes.Int32, Required: true},
-    iceberg.NestedField{ID: 3, Name: "baz", Type: iceberg.PrimitiveTypes.Bool, Required: false},
 )
 
-// Create a table identifier
-tableIdent := catalog.ToIdentifier("my_namespace", "my_table")
-
-// Create a table with optional properties
-tbl, err := cat.CreateTable(
-    context.Background(),
-    tableIdent,
-    schema,
-    catalog.WithProperties(map[string]string{"owner": "me"}),
-    catalog.WithLocation("s3://my-bucket/tables/my_table"),
-)
-if err != nil {
-    log.Fatal(err)
-}
+cat, err := catalog.Load(ctx, "default", iceberg.Properties{
+    "type":      "rest",
+    "uri":       "http://localhost:8181",
+    "warehouse": "s3://my-bucket/warehouse",
+})
 ```
 
-Also, you can load a table directly:
+### Namespaces
 
 ```go
-// Load an existing table
-tbl, err := cat.LoadTable(context.Background(), tableIdent, nil)
-if err != nil {
-    log.Fatal(err)
-}
+ns := table.Identifier{"sales"}
 
-fmt.Printf("Table: %s\n", tbl.Identifier())
-fmt.Printf("Location: %s\n", tbl.MetadataLocation())
+err := cat.CreateNamespace(ctx, ns, iceberg.Properties{"owner": "data-team"})
+
+namespaces, err := cat.ListNamespaces(ctx, nil) // []table.Identifier
+exists, err := cat.CheckNamespaceExists(ctx, ns)
+props, err := cat.LoadNamespaceProperties(ctx, ns)
+summary, err := cat.UpdateNamespaceProperties(ctx, ns,
+    []string{"deprecated"}, // removals
+    iceberg.Properties{"owner": "platform-team"}, // updates
+)
+err = cat.DropNamespace(ctx, ns)
 ```
 
-## Schema Creation
+`table.Identifier` is `[]string`; use `catalog.ToIdentifier("sales", "orders")` (or `catalog.ToIdentifier("sales.orders")`) to build one from string parts.
+
+### Tables
 
-Here are some examples of creating different types of schemas:
+#### Defining a schema
 
 ```go
-// Simple schema with primitive types
-simpleSchema := iceberg.NewSchemaWithIdentifiers(1, []int{2},
-    iceberg.NestedField{ID: 1, Name: "id", Type: iceberg.PrimitiveTypes.Int32, Required: true},
+import "github.com/apache/iceberg-go"
+
+schema := iceberg.NewSchema(1,
+    iceberg.NestedField{ID: 1, Name: "id", Type: iceberg.PrimitiveTypes.Int64, Required: true},
     iceberg.NestedField{ID: 2, Name: "name", Type: iceberg.PrimitiveTypes.String, Required: false},
     iceberg.NestedField{ID: 3, Name: "active", Type: iceberg.PrimitiveTypes.Bool, Required: false},
 )
-
-// Schema with nested struct
-nestedSchema := iceberg.NewSchemaWithIdentifiers(1, []int{1},
-    iceberg.NestedField{ID: 1, Name: "person", Type: &iceberg.StructType{
-        FieldList: []iceberg.NestedField{
-            {ID: 2, Name: "name", Type: iceberg.PrimitiveTypes.String, Required: false},
-            {ID: 3, Name: "age", Type: iceberg.PrimitiveTypes.Int32, Required: true},
-        },
-    }, Required: false},
-)
-
-// Schema with list and map types
-complexSchema := iceberg.NewSchemaWithIdentifiers(1, []int{1},
-    iceberg.NestedField{ID: 1, Name: "tags", Type: &iceberg.ListType{
-        ElementID: 2, Element: iceberg.PrimitiveTypes.String, ElementRequired: true,
-    }, Required: false},
-    iceberg.NestedField{ID: 3, Name: "metadata", Type: &iceberg.MapType{
-        KeyID: 4, KeyType: iceberg.PrimitiveTypes.String,
-        ValueID: 5, ValueType: iceberg.PrimitiveTypes.String, ValueRequired: true,
-    }, Required: false},
-)
 ```
 
-## Table Operations
+For nested types use `&iceberg.StructType{...}`, `&iceberg.ListType{...}`, or `&iceberg.MapType{...}`. Use `NewSchemaWithIdentifiers(id, identifierIDs, fields...)` to mark identifier columns.
 
-Here are some common table operations:
+#### Create
 
 ```go
-// List tables in a namespace
-tables := cat.ListTables(context.Background(), catalog.ToIdentifier("my_namespace"))
-for tableIdent, err := range tables {
-    if err != nil {
-        log.Printf("Error listing table: %v", err)
-        continue
-    }
-    fmt.Printf("Table: %v\n", tableIdent)
-}
-
-// Check if table exists
-exists, err := cat.CheckTableExists(context.Background(), tableIdent)
-if err != nil {
-    log.Fatal(err)
-}
-fmt.Printf("Table exists: %t\n", exists)
+import "github.com/apache/iceberg-go/catalog"
 
-// Drop a table
-err = cat.DropTable(context.Background(), tableIdent)
-if err != nil {
-    log.Fatal(err)
-}
+ident := catalog.ToIdentifier("sales", "orders")
 
-// Rename a table
-fromIdent := catalog.ToIdentifier("my_namespace", "old_table")
-toIdent := catalog.ToIdentifier("my_namespace", "new_table")
-renamedTable, err := cat.RenameTable(context.Background(), fromIdent, toIdent)
-if err != nil {
-    log.Fatal(err)
-}
+tbl, err := cat.CreateTable(ctx, ident, schema,
+    catalog.WithLocation("s3://my-bucket/sales/orders"),
+    catalog.WithProperties(iceberg.Properties{"owner": "data-team"}),
+)
 ```
 
-## Working with Table Metadata
+Optional `catalog.WithPartitionSpec`, `catalog.WithSortOrder`, and `catalog.WithStagedUpdates` are also available.
 
-Once you have a table, you can access its metadata and properties:
+#### Load, exists, list, drop, rename
 
 ```go
-// Access table metadata
-metadata := tbl.Metadata()
-fmt.Printf("Table UUID: %s\n", metadata.TableUUID())
-fmt.Printf("Format version: %d\n", metadata.Version())
-fmt.Printf("Last updated: %d\n", metadata.LastUpdatedMillis())
-
-// Access table schema
-schema := tbl.Schema()
-fmt.Printf("Schema ID: %d\n", schema.ID)
-fmt.Printf("Number of fields: %d\n", schema.NumFields())
-
-// Access table properties
-props := tbl.Properties()
-fmt.Printf("Owner: %s\n", props["owner"])
-
-// Access the current snapshot
-if snapshot := tbl.CurrentSnapshot(); snapshot != nil {
-    fmt.Printf("Current snapshot ID: %d\n", snapshot.SnapshotID)
-    fmt.Printf("Snapshot timestamp: %d\n", snapshot.TimestampMs)
-}
+tbl, err := cat.LoadTable(ctx, ident)
+
+exists, err := cat.CheckTableExists(ctx, ident)
 
-// List all snapshots
-for _, snapshot := range tbl.Snapshots() {
-    fmt.Printf("Snapshot %d: %s\n", snapshot.SnapshotID, snapshot.Summary.Operation)
+for ident, err := range cat.ListTables(ctx, table.Identifier{"sales"}) {
+    if err != nil { /* ... */ }
+    fmt.Println(ident)
 }
+
+err = cat.DropTable(ctx, ident)
+
+renamed, err := cat.RenameTable(ctx,
+    catalog.ToIdentifier("sales", "orders"),
+    catalog.ToIdentifier("sales", "orders_v2"))
 ```
 
-## Creating Tables with Partitioning
+`ListTables` returns an `iter.Seq2[table.Identifier, error]` that streams results.
 
-You can create tables with partitioning:
+#### Inspecting metadata
 
 ```go
-import (
-    "github.com/apache/iceberg-go"
-    "github.com/apache/iceberg-go/catalog"
-)
+tbl.Identifier()         // table.Identifier
+tbl.Location()           // string
+tbl.MetadataLocation()   // string (path of current metadata.json)
+tbl.Metadata()           // table.Metadata
+tbl.Schema()             // *iceberg.Schema (current)
+tbl.Schemas()            // map[int]*iceberg.Schema
+tbl.Spec()               // iceberg.PartitionSpec
+tbl.SortOrder()          // table.SortOrder
+tbl.Properties()         // iceberg.Properties
 
-// Create schema
-schema := iceberg.NewSchemaWithIdentifiers(1, []int{1},
-    iceberg.NestedField{ID: 1, Name: "id", Type: iceberg.PrimitiveTypes.Int32, Required: true},
-    iceberg.NestedField{ID: 2, Name: "name", Type: iceberg.PrimitiveTypes.String, Required: false},
-    iceberg.NestedField{ID: 3, Name: "date", Type: iceberg.PrimitiveTypes.Date, Required: false},
-)
+if snap := tbl.CurrentSnapshot(); snap != nil {
+    fmt.Println(snap.SnapshotID, snap.TimestampMs, snap.Summary)
+}
 
-// Create a partition spec
-partitionSpec := iceberg.NewPartitionSpec(
-    iceberg.PartitionField{SourceID: 3, FieldID: 1000, Transform: iceberg.IdentityTransform{}, Name: "date"},
-)
+// All snapshots
+for _, snap := range tbl.Metadata().Snapshots() {
+    fmt.Println(snap.SnapshotID)
+}
 
-// Create a table with partitioning
-tbl, err := cat.CreateTable(
-    context.Background(),
-    tableIdent,
-    schema,
-    catalog.WithPartitionSpec(&partitionSpec),
-    catalog.WithLocation("s3://my-bucket/tables/partitioned_table"),
-)
-if err != nil {
-    log.Fatal(err)
+// Stream all manifest files across all snapshots
+for mf, err := range tbl.AllManifests(ctx) {
+    if err != nil { /* ... */ }
+    fmt.Println(mf.FilePath())
 }
 ```
 
-# Scanning (Reading Data)
+## Reading data
 
-The `Scan` API reads data from Iceberg tables as Apache Arrow record batches. It supports
-column projection, row filtering, snapshot selection, and time travel.
+`(t Table) Scan(opts ...ScanOption) *Scan` returns a scan that you can resolve into Arrow data.
 
-## Basic Scan
-
-### Streaming Record Batches
+### Streaming record batches
 
 ```go
-import (
-    "context"
-    "fmt"
-
-    "github.com/apache/iceberg-go/table"
-)
+import "github.com/apache/iceberg-go/table"
 
-// Stream record batches one at a time — only one batch
-// is in memory at any point.
 scan := tbl.Scan()
-arrowSchema, records, err := scan.ToArrowRecords(context.Background())
-if err != nil {
-    log.Fatal(err)
-}
+arrowSchema, batches, err := scan.ToArrowRecords(ctx)
+if err != nil { /* ... */ }
 
-fmt.Printf("Schema: %s\n", arrowSchema)
-for batch, err := range records {
-    if err != nil {
-        log.Fatal(err)
-    }
-    fmt.Printf("Batch with %d rows\n", batch.NumRows())
+fmt.Println(arrowSchema)
+for batch, err := range batches {
+    if err != nil { /* ... */ }
+    fmt.Printf("batch with %d rows\n", batch.NumRows())
     batch.Release()
 }
 ```
 
+`ToArrowRecords` returns `iter.Seq2[arrow.RecordBatch, error]` so only one batch is in memory at a time. Always call `batch.Release()` to free Arrow buffers.
+
 ### Materializing as an Arrow Table
 
 ```go
-// Materialize all record batches into a single Arrow Table.
-scan := tbl.Scan()
-arrowTable, err := scan.ToArrowTable(context.Background())
-if err != nil {
-    log.Fatal(err)
-}
-defer arrowTable.Release()
-
-fmt.Printf("Read %d rows in %d columns\n",
-    arrowTable.NumRows(), arrowTable.NumCols())
+arrowTbl, err := tbl.Scan().ToArrowTable(ctx)
+if err != nil { /* ... */ }
+defer arrowTbl.Release()
+fmt.Printf("%d rows in %d cols\n", arrowTbl.NumRows(), arrowTbl.NumCols())
 ```
 
-## Column Selection and Row Filtering
+### Projection and filters
 
 ```go
 import "github.com/apache/iceberg-go"
 
-// Select specific columns and filter rows
 scan := tbl.Scan(
-    table.WithSelectedFields("id", "name", "date"),
+    table.WithSelectedFields("id", "name"),
     table.WithRowFilter(
-        iceberg.GreaterThanEqual(iceberg.Reference("id"), int32(100)),
+        iceberg.NewAnd(
+            iceberg.GreaterThanEqual(iceberg.Reference("id"), int64(100)),
+            iceberg.IsIn(iceberg.Reference("region"), "us-east", "us-west"),
+        ),
     ),
-    table.WithCaseSensitive(true),
     table.WithLimit(1000),
+    table.WithCaseSensitive(true),
 )
-
-arrowSchema, records, err := scan.ToArrowRecords(context.Background())
-if err != nil {
-    log.Fatal(err)
-}
 ```
 
-## Time Travel
+For the predicate vocabulary, see [Row Filter Syntax](./row-filter-syntax.md).
+
+### Time travel
 
 ```go
-// Read a specific snapshot by ID
-scan := tbl.Scan(
-    table.WithSnapshotID(snapshotID),
-)
+// By snapshot ID
+scan := tbl.Scan(table.WithSnapshotID(snap.SnapshotID))
 
-// Read data as of a specific timestamp (milliseconds since epoch)
-scan = tbl.Scan(
-    table.WithSnapshotAsOf(timestampMs),
-)
+// As of a timestamp (milliseconds since epoch)
+scan = tbl.Scan(table.WithSnapshotAsOf(time.Now().Add(-24*time.Hour).UnixMilli()))
+```
 
-// Read from a named branch or tag
-scan = tbl.Scan()
-scan, err := scan.UseRef("audit-branch")
-if err != nil {
-    log.Fatal(err)
-}
+### Reading from a branch or tag
+
+```go
+scan, err := tbl.Scan().UseRef("audit-branch")
+if err != nil { /* ... */ }
+
+arrowTbl, err := scan.ToArrowTable(ctx)
 ```
 
-## Reading as an Arrow Table
+### Iterating tasks for custom processing
+
+If you need finer control (custom file readers, distributed scan planning):
 
 ```go
-// Load all results into a single Arrow Table (in-memory)
-arrowTable, err := tbl.Scan().ToArrowTable(context.Background())
-if err != nil {
-    log.Fatal(err)
-}
-defer arrowTable.Release()
+scan := tbl.Scan(table.WithRowFilter(myFilter))
+tasks, err := scan.PlanFiles(ctx)
+if err != nil { /* ... */ }
 
-fmt.Printf("Total rows: %d\n", arrowTable.NumRows())
-fmt.Printf("Total columns: %d\n", arrowTable.NumCols())
+arrowSchema, batches, err := scan.ReadTasks(ctx, tasks)
 ```
 
-# Writing Data
+## Writing data
 
-The write API uses Apache Arrow as the input format. Data can be written using
-`arrow.Table` or `array.RecordReader` (streaming).
+The shortcut methods on `Table` open a transaction, perform the write, and commit. Use `NewTransaction` directly when you need to combine multiple operations.
 
-## Append Data
+### Append
 
 ```go
 import (
-    "context"
-
-    "github.com/apache/arrow-go/v18/arrow"
     "github.com/apache/arrow-go/v18/arrow/array"
-    "github.com/apache/arrow-go/v18/arrow/memory"
 )
 
-// Append using a RecordReader (streaming)
-// The RecordReader's schema must be compatible with the table schema.
-newTable, err := tbl.Append(context.Background(), recordReader, nil)
-if err != nil {
-    log.Fatal(err)
-}
+// From a streaming RecordReader
+newTbl, err := tbl.Append(ctx, recordReader, nil /* snapshot props */)
 
-// Append using an Arrow Table with a batch size
-newTable, err = tbl.AppendTable(context.Background(), arrowTable, 1024, nil)
-if err != nil {
-    log.Fatal(err)
-}
+// From an in-memory Arrow Table; batchSize controls the rolling writer
+newTbl, err = tbl.AppendTable(ctx, arrowTbl, 1024, nil)
 ```
 
-## Overwrite Data
-
-Overwrite replaces existing data. An optional filter controls which rows are replaced.
+### Overwrite
 
 ```go
-import "github.com/apache/iceberg-go"
+import "github.com/apache/iceberg-go/table"
 
-// Overwrite all existing data with new data
-newTable, err := tbl.Overwrite(context.Background(), recordReader, nil)
-if err != nil {
-    log.Fatal(err)
-}
+// Replace all data
+newTbl, err := tbl.Overwrite(ctx, recordReader, nil)
 
-// Overwrite only rows matching a filter
-newTable, err = tbl.Overwrite(context.Background(), recordReader, nil,
+// Replace only rows matching a filter
+newTbl, err = tbl.Overwrite(ctx, recordReader, nil,
     table.WithOverwriteFilter(
-        iceberg.EqualTo(iceberg.Reference("date"), "2024-01-01"),
+        iceberg.EqualTo(iceberg.Reference("date"), "2026-01-01"),
     ),
 )
-if err != nil {
-    log.Fatal(err)
-}
 ```
 
-## Delete Data
+`OverwriteTable` is the `arrow.Table` variant.
 
-Delete removes rows matching a filter expression.
+### Delete
 
 ```go
-import "github.com/apache/iceberg-go"
-
-// Delete rows matching a filter
-newTable, err := tbl.Delete(context.Background(),
-    iceberg.LessThan(iceberg.Reference("id"), int32(100)),
-    nil, // snapshot properties
+newTbl, err := tbl.Delete(ctx,
+    iceberg.LessThan(iceberg.Reference("id"), int64(100)),
+    nil, /* snapshot props */
 )
-if err != nil {
-    log.Fatal(err)
-}
 ```
 
-# Transactions
-
-Transactions group multiple operations into a single atomic commit. Use transactions
-when you need to perform multiple writes or metadata changes together.
+### Add existing files
 
-## Basic Transaction
+When you already have data files (e.g. produced by another writer), register them without rewriting:
 
 ```go
-import (
-    "context"
+txn := tbl.NewTransaction()
+err := txn.AddFiles(ctx, []string{
+    "s3://my-bucket/sales/orders/data/file-1.parquet",
+    "s3://my-bucket/sales/orders/data/file-2.parquet",
+}, nil /* snapshot props */, false /* ignoreDuplicates */)
+if err != nil { /* ... */ }
 
-    "github.com/apache/iceberg-go"
-)
+newTbl, err := txn.Commit(ctx)
+```
+
+`ReplaceDataFiles(ctx, filesToDelete, filesToAdd, snapshotProps)` and `ReplaceDataFilesWithDataFiles(ctx, filesToDelete, dataFilesToAdd, snapshotProps, opts...)` are also available on `*Transaction` for swapping files atomically.
 
+### Transactions
+
+Group writes and metadata changes into one atomic snapshot:
+
+```go
 txn := tbl.NewTransaction()
 
-// Append new data
-err := txn.Append(context.Background(), recordReader, nil)
-if err != nil {
-    log.Fatal(err)
+if err := txn.Delete(ctx,
+    iceberg.LessThan(iceberg.Reference("date"), "2026-01-01"), nil); err != nil {
+    /* ... */
 }
-
-// Set table properties
-err = txn.SetProperties(iceberg.Properties{
-    "commit.user": "data-pipeline",
-})
-if err != nil {
-    log.Fatal(err)
+if err := txn.Append(ctx, recordReader, nil); err != nil {
+    /* ... */
 }
-
-// Commit all changes atomically
-newTable, err := txn.Commit(context.Background())
-if err != nil {
-    log.Fatal(err)
+if err := txn.SetProperties(iceberg.Properties{"commit.user": "data-pipeline"}); err != nil {
+    /* ... */
 }
+
+newTbl, err := txn.Commit(ctx)
+```
+
+To target a specific branch:
+
+```go
+txn := tbl.NewTransactionOnBranch("staging")
 ```
 
-## Multi-Operation Transaction
+`Commit` retries automatically on conflict (`ErrCommitFailed`) - tune via the `commit.retry.*` table properties.
+
+## Schema and partition evolution
+
+### Schema evolution
 
 ```go
+import "github.com/apache/iceberg-go/table"
+
 txn := tbl.NewTransaction()
 
-// Delete old data
-err := txn.Delete(context.Background(),
-    iceberg.LessThan(iceberg.Reference("date"), "2023-01-01"),
-    nil,
-)
-if err != nil {
-    log.Fatal(err)
+err := table.NewUpdateSchema(txn, true /* caseSensitive */, false /* allowIncompatibleChanges */).
+    AddColumn([]string{"tip"}, iceberg.PrimitiveTypes.Float64, "Tip in dollars", false, nil).
+    RenameColumn([]string{"name"}, "full_name").
+    DeleteColumn([]string{"deprecated_field"}).
+    Commit()
+if err != nil { /* ... */ }
+
+newTbl, err := txn.Commit(ctx)
+```
+
+Reorder fields with `MoveFirst`, `MoveBefore`, or `MoveAfter`. Set `allowIncompatibleChanges` to `true` to permit type narrowing or making optional columns required.
+
+### Partition evolution
+
+```go
+us := table.NewUpdateSpec(txn, true /* caseSensitive */)
+us.AddField("event_time", iceberg.DayTransform{}, "event_day") // sourceColName, transform, partitionFieldName
+us.RemoveField("legacy_partition")
+if err := us.Commit(); err != nil { /* ... */ }
+```
+
+`AddField` chains; `AddIdentity(sourceCol)` is a shortcut for an identity transform; `RenameField(name, newName)` renames an existing partition field.
+
+Available transforms (root `iceberg` package): `IdentityTransform{}`, `YearTransform{}`, `MonthTransform{}`, `DayTransform{}`, `HourTransform{}`, `BucketTransform{NumBuckets: N}`, `TruncateTransform{Width: W}`.
+
+## Snapshots and refs
+
+### Inspecting
+
+```go
+if snap := tbl.CurrentSnapshot(); snap != nil {
+    fmt.Println(snap.SnapshotID, snap.TimestampMs, snap.Summary)
 }
+snap := tbl.SnapshotByID(snapshotID)
+named := tbl.SnapshotByName("audit")
 
-// Append replacement data
-err = txn.Append(context.Background(), recordReader, nil)
-if err != nil {
-    log.Fatal(err)
+for _, s := range tbl.Metadata().Snapshots() {
+    fmt.Println(s.SnapshotID, s.Summary)
 }
+```
 
-// Commit both operations as one atomic snapshot
-newTable, err := txn.Commit(context.Background())
-if err != nil {
-    log.Fatal(err)
+### Branches and tags
+
+The CLI's `branch create` and `tag create` commands ([CLI](./cli.md)) are the most ergonomic surface today. Programmatically, ref creation goes through `Catalog.CommitTable` with a `SetSnapshotRef` update:
+
+```go
+import "github.com/apache/iceberg-go/table"
+
+snap := tbl.CurrentSnapshot()
+update := table.NewSetSnapshotRefUpdate(
+    "audit",                  // ref name
+    snap.SnapshotID,
+    table.BranchRef,          // or table.TagRef
+    0,                        // maxRefAgeMs (0 = unset)
+    0,                        // maxSnapshotAgeMs (0 = unset)
+    0,                        // minSnapshotsToKeep (0 = unset)
+)
+reqs := []table.Requirement{
+    table.AssertTableUUID(tbl.Metadata().TableUUID()),
+    table.AssertRefSnapshotID("audit", nil), // ref must not already exist
 }
+
+_, _, err := cat.CommitTable(ctx, tbl.Identifier(), reqs, []table.Update{update})
 ```
 
-## Branch Transactions
+Constants `table.MainBranch`, `table.BranchRef`, `table.TagRef` live in [`table/refs.go`](https://github.com/apache/iceberg-go/blob/main/table/refs.go). A higher-level builder is on the roadmap.
+
+### Expiration and rollback
 
 ```go
-// Create a transaction that commits to a specific branch
-txn := tbl.NewTransactionOnBranch("staging")
+// Expire snapshots older than the table's retention properties
+err := txn.ExpireSnapshots(/* options */)
 
-err := txn.Append(context.Background(), recordReader, nil)
-if err != nil {
-    log.Fatal(err)
-}
+// Roll back to a previous snapshot
+err = txn.RollbackToSnapshot(targetSnapshotID)
+```
 
-newTable, err := txn.Commit(context.Background())
-if err != nil {
-    log.Fatal(err)
-}
+Tune retention with the `min-snapshots-to-keep`, `max-snapshot-age-ms`, and `max-ref-age-ms` table properties (see [Configuration](./configuration.md)).
+
+## Maintenance
+
+### Orphan file cleanup
+
+```go
+import (
+    "time"
+
+    "github.com/apache/iceberg-go/table"
+)
+
+result, err := tbl.DeleteOrphanFiles(ctx,
+    table.WithFilesOlderThan(72*time.Hour),
+    table.WithDryRun(false),
+    table.WithMaxConcurrency(8),
+)
+if err != nil { /* ... */ }
+fmt.Printf("removed %d files\n", len(result.DeletedFiles))
+```
+
+Also see `table.WithLocation`, `table.WithDeleteFunc`, `table.WithPrefixMismatchMode`, `table.WithEqualSchemes`, and `table.WithEqualAuthorities` in `table/orphan_cleanup.go`.
+
+### Compaction (rewrite data files)
+
+```go
+import "github.com/apache/iceberg-go/table"
+
+txn := tbl.NewTransaction()
+result, err := txn.RewriteDataFiles(ctx, groups /* []table.CompactionTaskGroup */, table.RewriteDataFilesOptions{})
+if err != nil { /* ... */ }
+
+newTbl, err := txn.Commit(ctx)
+fmt.Printf("rewrote %d files into %d (%d -> %d bytes)\n",
+    result.RemovedDataFiles, result.AddedDataFiles, result.BytesBefore, result.BytesAfter)
+```
+
+The `table/compaction` subpackage provides bin-packing planning. The `iceberg compact analyze` and `compact run` CLI commands wrap the same machinery - see [CLI](./cli.md).
+
+## Views
+
+Views are created and loaded through catalogs that support them (REST, Hive, SQL):
+
+```go
+import "github.com/apache/iceberg-go/view"
+
+// Create
+v, err := view.CreateView(
+    ctx,
+    "my-catalog",
+    table.Identifier{"analytics", "monthly_orders"},
+    schema,
+    "SELECT month, sum(amount) FROM orders GROUP BY month",
+    table.Identifier{"sales"},                      // default namespace for unqualified names
+    "s3://my-bucket/views/monthly_orders",
+    iceberg.Properties{},
+)
+
+// Inspect
+v.CurrentVersion()      // *view.Version
+v.CurrentSchema()       // *iceberg.Schema
+v.Versions()            // []*view.Version
+v.Schemas()             // map[int]*iceberg.Schema
+v.Properties()          // iceberg.Properties
 ```
+
+`view.New(ident, meta, metadataLocation)` constructs a view from already-loaded metadata; `view.NewFromLocation(ctx, ident, metadataLocation, fsysFactory)` loads metadata from disk or object storage.
+
+## Iceberg ↔ Arrow types
+
+When iceberg-go converts an Iceberg schema to Arrow (e.g. for the scanner output) or vice versa, the type mapping is:
+
+| Iceberg type | Arrow type |
+|---|---|
+| `boolean` | `arrow.FixedWidthTypes.Boolean` |
+| `int` | `arrow.PrimitiveTypes.Int32` |
+| `long` | `arrow.PrimitiveTypes.Int64` |
+| `float` | `arrow.PrimitiveTypes.Float32` |
+| `double` | `arrow.PrimitiveTypes.Float64` |
+| `decimal(p, s)` | `arrow.Decimal128Type{Precision: p, Scale: s}` |
+| `date` | `arrow.FixedWidthTypes.Date32` |
+| `time` | `arrow.FixedWidthTypes.Time64us` |
+| `timestamp` | `&arrow.TimestampType{Unit: arrow.Microsecond}` (no zone) |
+| `timestamptz` | `arrow.FixedWidthTypes.Timestamp_us` (`UTC` zone) |
+| `timestamp_ns` | `&arrow.TimestampType{Unit: arrow.Nanosecond}` (no zone) |
+| `timestamptz_ns` | `arrow.FixedWidthTypes.Timestamp_ns` (`UTC` zone) |
+| `string` | `arrow.BinaryTypes.String` |
+| `binary` | `arrow.BinaryTypes.Binary` |
+| `fixed[L]` | `&arrow.FixedSizeBinaryType{ByteWidth: L}` |
+| `uuid` | `arrow.FixedWidthTypes.UUID` (extension type) |
+| `struct<...>` | `arrow.StructOf(...)` |
+| `list<E>` | `arrow.ListOf(E)` (or `LargeListOf` if `useLargeTypes`) |
+| `map<K, V>` | `arrow.MapOf(K, V)` |
+| `variant` | `arrow.ExtensionType` for Variant |
+
+Helpers in [`table/arrow_utils.go`](https://github.com/apache/iceberg-go/blob/main/table/arrow_utils.go):
+
+- `SchemaToArrowSchema(sc *iceberg.Schema, nameMapping NameMapping, useLargeTypes, includeRowLineage bool) (*arrow.Schema, error)`
+- `VisitArrowSchema[T](sc *arrow.Schema, visitor ArrowSchemaVisitor[T]) (T, error)`
+
+For a writer-side schema (Arrow → Iceberg), the scanner and writers handle conversion automatically as long as your Arrow schema is compatible with the table schema.
diff --git a/website/src/community.md b/website/src/community.md
new file mode 100644
index 00000000..6c8bede3
--- /dev/null
+++ b/website/src/community.md
@@ -0,0 +1,45 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements.  See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership.  The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License.  You may obtain a copy of the License at
+  ~
+  ~   http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied.  See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+-->
+
+# Community
+
+Apache Iceberg Go is developed in the open as part of the broader Apache Iceberg project. The fastest ways to ask questions, share work, and follow development are below.
+
+## Chat
+
+- [#iceberg-go on Apache Iceberg Slack](https://apache-iceberg.slack.com/archives/C05J3MJ42BD) - day-to-day discussion, design questions, help requests.
+
+## Mailing list
+
+The Apache Iceberg project uses a single dev mailing list across all language implementations.
+
+- Read / post: `dev@iceberg.apache.org`
+- Subscribe: send any email to `dev-subscribe@iceberg.apache.org`
+
+## Issues and pull requests
+
+- [Issue tracker](https://github.com/apache/iceberg-go/issues)
+- [Pull requests](https://github.com/apache/iceberg-go/pulls)
+
+For contribution guidelines, see [Contributing](./contributing.md).
+
+## Apache Iceberg community at large
+
+- [Apache Iceberg community page](https://iceberg.apache.org/community/) - cross-implementation links, sync calls, and the project Code of Conduct.
+- [Apache Iceberg Code of Conduct](https://www.apache.org/foundation/policies/conduct.html) - applies to all participation in this project.
diff --git a/website/src/configuration.md b/website/src/configuration.md
new file mode 100644
index 00000000..dab9dc4f
--- /dev/null
+++ b/website/src/configuration.md
@@ -0,0 +1,336 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements.  See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership.  The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License.  You may obtain a copy of the License at
+  ~
+  ~   http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied.  See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+-->
+
+# Configuration
+
+This page documents how to configure Apache Iceberg Go: the CLI's YAML config file, per-catalog `Option` surfaces, file-system credentials, table write properties, concurrency, and how to plug in custom catalogs and IO backends.
+
+Only properties and options that the iceberg-go code actually reads are listed. Properties defined in the Apache Iceberg spec but not yet wired into iceberg-go are intentionally omitted - check `pkg.go.dev/github.com/apache/iceberg-go` for the latest read sites.
+
+## CLI configuration file
+
+The `iceberg` CLI loads catalog defaults from `~/.iceberg-go.yaml` (override the directory with `GOICEBERG_HOME`). The schema, defined in [`config/config.go`](https://github.com/apache/iceberg-go/blob/main/config/config.go), is:
+
+```yaml
+default-catalog: default
+max-workers: 5
+catalog:
+  default:
+    type: rest
+    uri: https://example.com/iceberg
+    warehouse: s3://my-bucket/warehouse
+    credential: <client-id>:<client-secret>
+    output: text
+    rest:
+      sigv4-enabled: false
+      signing-name: ""
+      signing-region: ""
+```
+
+| Key | Purpose |
+|---|---|
+| `default-catalog` | Name used when `--catalog-name` is not passed on the CLI. |
+| `max-workers` | Worker pool size for concurrent operations. Default `5`. |
+| `catalog.<name>.type` | One of `rest`, `hive`, `glue`, `sql`, `hadoop`. |
+| `catalog.<name>.uri` | Catalog endpoint or DSN. |
+| `catalog.<name>.warehouse` | Warehouse identifier (REST/Glue) or location (Hive/SQL). |
+| `catalog.<name>.credential` | Credential string passed through to the catalog's auth handler. |
+| `catalog.<name>.output` | CLI output format (e.g. `text`, `json`). |
+| `catalog.<name>.rest.sigv4-enabled` | Enable AWS SigV4 signing for REST. |
+| `catalog.<name>.rest.signing-name` | SigV4 service name. |
+| `catalog.<name>.rest.signing-region` | SigV4 region. |
+
+## Catalog options
+
+Each catalog package exposes its own functional `Option` set. The lists below reflect the public option surface; `pkg.go.dev` is authoritative for the current set.
+
+### REST (`catalog/rest`)
+
+The most option-rich surface. Source: [`catalog/rest/options.go`](https://github.com/apache/iceberg-go/blob/main/catalog/rest/options.go).
+
+| Group | Options |
+|---|---|
+| Authentication | `WithCredential`, `WithOAuthToken`, `WithAuthManager`, `WithAuthURI`, `WithScope`, `WithAudience`, `WithResource` |
+| AWS SigV4 | `WithSigV4`, `WithSigV4RegionSvc`, `WithAwsConfig` |
+| HTTP | `WithHeaders`, `WithTLSConfig`, `WithOAuthTLSConfig`, `WithCustomTransport` |
+| Catalog routing | `WithPrefix`, `WithWarehouseLocation`, `WithMetadataLocation` |
+| Pass-through | `WithAdditionalProps` |
+
+### Hive (`catalog/hive`)
+
+Source: [`catalog/hive/options.go`](https://github.com/apache/iceberg-go/blob/main/catalog/hive/options.go).
+
+- `WithURI(uri string)` - Thrift URI for the Hive Metastore (e.g. `thrift://127.0.0.1:9083`).
+- `WithWarehouse(warehouse string)`
+- `WithProperties(props iceberg.Properties)`
+
+### Glue (`catalog/glue`)
+
+Source: [`catalog/glue/options.go`](https://github.com/apache/iceberg-go/blob/main/catalog/glue/options.go).
+
+- `WithAwsConfig(cfg aws.Config)` - AWS SDK v2 config; respects the AWS default credential chain.
+- `WithAwsProperties(props AwsProperties)` - explicit overrides for region/endpoint/access keys.
+
+### SQL (`catalog/sql`)
+
+The SQL catalog has no functional-option surface. Construct it with `NewCatalog`:
+
+```go
+db, _ := sql.Open(sqliteshim.ShimName, "file:catalog.db")
+cat, err := sqlcat.NewCatalog("default", db, sqlcat.SQLite, iceberg.Properties{
+    "warehouse": "file:///tmp/warehouse",
+})
+```
+
+Supported dialects: `sqlcat.Postgres`, `sqlcat.MySQL`, `sqlcat.SQLite`, `sqlcat.MSSQL`, `sqlcat.Oracle` (`catalog/sql/sql.go:50`).
+
+### Shared options on the base `catalog` package
+
+Operations that create or update tables/views accept these (`catalog/catalog.go`):
+
+- `WithLocation`, `WithPartitionSpec`, `WithSortOrder`, `WithProperties`, `WithStagedUpdates`
+- View-specific: `WithViewLocation`, `WithViewProperties`
+
+## File-system credentials
+
+iceberg-go registers the local file system (`file://`) automatically. Cloud schemes are *not* registered until you add a blank import:
+
+```go
+import _ "github.com/apache/iceberg-go/io/gocloud"
+```
+
+The `init()` function in [`io/gocloud/register.go`](https://github.com/apache/iceberg-go/blob/main/io/gocloud/register.go) registers `s3`, `s3a`, `s3n`, `oss`, `gs`, `abfs`, `abfss`, `wasb`, and `wasbs`. Without the blank import, these schemes return `ErrIOSchemeNotFound` with a hint to add the import.
+
+All credential and tuning property keys are constants in [`io/config.go`](https://github.com/apache/iceberg-go/blob/main/io/config.go). They can be supplied through table properties, catalog properties, or per-call `iceberg.Properties` arguments depending on context.
+
+### S3
+
+Authentication is resolved in this order (`io/gocloud/s3.go`):
+
+1. Static credentials in properties: `s3.access-key-id` + `s3.secret-access-key` (+ optional `s3.session-token`).
+2. The standard AWS SDK v2 default credential chain - environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`), `~/.aws/credentials`, container/IAM role.
+
+Tuning properties:
+
+| Key (constant) | Purpose |
+|---|---|
+| `s3.region` (`io.S3Region`) / `client.region` (`io.S3ClientRegion`) | AWS region. |
+| `s3.endpoint` (`io.S3EndpointURL`) | Override S3 endpoint URL (custom or compatible storage). Falls back to `AWS_S3_ENDPOINT` env. |
+| `s3.access-key-id` (`io.S3AccessKeyID`) | Static access key. |
+| `s3.secret-access-key` (`io.S3SecretAccessKey`) | Static secret key. |
+| `s3.session-token` (`io.S3SessionToken`) | Static session token. |
+| `s3.proxy-uri` (`io.S3ProxyURI`) | HTTP proxy URL. |
+| `s3.connect-timeout` (`io.S3ConnectTimeout`) | Either a number of seconds (`"60"`, `"60.0"`) or a Go duration (`"5s"`). |
+| `s3.force-virtual-addressing` (`io.S3ForceVirtualAddressing`) | Force virtual-host-style addressing. |
+| `s3.signer.uri` (`io.S3SignerURI`) | Reserved for remote-signing endpoint (not yet implemented). |
+
+### Google Cloud Storage
+
+Authentication resolution (`io/gocloud/gcs.go`):
+
+1. Explicit JSON key bytes via `gcs.jsonkey` or path via `gcs.keypath`.
+2. Optional `gcs.credtype` selecting one of `service_account`, `authorized_user`, `impersonated_service_account`, `external_account`.
+3. The GCP default credentials chain (`gcp.DefaultCredentials`) - falls back to anonymous if no creds are found.
+
+Tuning properties:
+
+| Key (constant) | Purpose |
+|---|---|
+| `gcs.endpoint` (`io.GCSEndpoint`) | Custom GCS endpoint URL. |
+| `gcs.keypath` (`io.GCSKeyPath`) | Path to a JSON service-account key file. |
+| `gcs.jsonkey` (`io.GCSJSONKey`) | JSON key as a string. |
+| `gcs.credtype` (`io.GCSCredType`) | Credential type override. |
+| `gcs.usejsonapi` (`io.GCSUseJSONAPI`) | Set to any value to enable the GCS JSON API for reads. |
+
+### Azure Data Lake Storage / Blob
+
+Authentication is selected based on the property keys present (`io/gocloud/azure.go`):
+
+1. Shared key: both `adls.auth.shared-key.account.name` and `adls.auth.shared-key.account.key` set.
+2. Per-host SAS token: `adls.sas-token.<hostname>` (prefix-matched against the storage account host).
+3. Per-host connection string: `adls.connection-string.<hostname>`.
+4. Managed identity: `adls.auth.managed-identity.enabled` set to a truthy value.
+
+Tuning properties:
+
+| Key (constant) | Purpose |
+|---|---|
+| `adls.auth.shared-key.account.name` (`io.ADLSSharedKeyAccountName`) | Account name. |
+| `adls.auth.shared-key.account.key` (`io.ADLSSharedKeyAccountKey`) | Account key. |
+| `adls.sas-token.<host>` (prefix `io.ADLSSasTokenPrefix`) | Per-host SAS token. |
+| `adls.connection-string.<host>` (prefix `io.ADLSConnectionStringPrefix`) | Per-host connection string. |
+| `adls.client-id` (`io.ADLSClientID`) | Client/application ID for AAD auth. |
+| `adls.endpoint` (`io.ADLSEndpoint`) | Storage domain (e.g. `blob.core.windows.net`). |
+| `adls.protocol` (`io.ADLSProtocol`) | `http` or `https`. |
+| `adls.auth.managed-identity.enabled` (`io.ADLSManagedIdentityEnabled`) | Enable Azure Managed Identity auth. |
+
+## Environment variables
+
+iceberg-go reads only a small set of environment variables directly. AWS / GCP / Azure credentials flow through the respective SDKs, not through iceberg-go-defined env vars.
+
+| Variable | Purpose | Read at |
+|---|---|---|
+| `GOICEBERG_HOME` | Directory containing `.iceberg-go.yaml`. Defaults to the user's home directory. | `config/config.go:87` |
+| `ICEBERG_SQL_DEBUG` | SQL catalog query logging - `1` (failed queries), `2` (all queries). | `catalog/sql/sql.go:206` |
+| `AWS_S3_ENDPOINT` | Fallback S3 endpoint when `s3.endpoint` is unset. | `io/gocloud/s3.go:193` |
+
+There is no `PYICEBERG_*`-style env var convention. Use the YAML config file or pass `iceberg.Properties` to overrides programmatically.
+
+## Concurrency
+
+| Setting | Source | Effect |
+|---|---|---|
+| `max-workers` in `~/.iceberg-go.yaml` (`config.EnvConfig.MaxWorkers`) | YAML config | Worker pool size used by parallel column writes, snapshot producers, scan plan, equality-delete writers. Default `5`. |
+| `WitMaxConcurrency(n int) ScanOption` | Code (`table.WitMaxConcurrency`) | Per-scan override. Note: function name is `Wit...` (not `With...`) - this is a pre-existing typo in the public API. |
+| `WithMaxWriteWorkers(n int)` | Code (per-write API on `WriteRecords`) | Per-write override of the worker count. |
+| `WithClusteredWrite()` | Code (per-write API on `WriteRecords`) | Forces single-threaded writes. Mutually exclusive with `WithMaxWriteWorkers`. |
+
+## Pluggability
+
+Two registries are user-extensible. The third (LocationProvider) is currently informational.
+
+### IO scheme registry
+
+Register a custom URL scheme with [`io.Register`](https://github.com/apache/iceberg-go/blob/main/io/registry.go):
+
+```go
+import (
+    "context"
+    "net/url"
+
+    "github.com/apache/iceberg-go/io"
+)
+
+func init() {
+    io.Register("myfs", func(ctx context.Context, parsed *url.URL, props map[string]string) (io.IO, error) {
+        return newMyFS(parsed, props)
+    })
+}
+```
+
+`io.Register` panics on `nil` factory or duplicate scheme. Built-in schemes: `file`, `""` (the empty scheme). Cloud schemes (`s3`, `gs`, `abfs`, etc.) are registered by `io/gocloud` only when its package is blank-imported.
+
+`io.GetRegisteredSchemes()` returns the current scheme list; `io.Unregister(scheme)` removes one.
+
+### Catalog type registry
+
+Register a custom catalog type with [`catalog.Register`](https://github.com/apache/iceberg-go/blob/main/catalog/registry.go):
+
+```go
+import (
+    "context"
+
+    "github.com/apache/iceberg-go"
+    "github.com/apache/iceberg-go/catalog"
+)
+
+func init() {
+    catalog.Register("mycatalog", catalog.RegistrarFunc(
+        func(ctx context.Context, name string, props iceberg.Properties) (catalog.Catalog, error) {
+            return newMyCatalog(name, props)
+        },
+    ))
+}
+```
+
+After registration, `catalog.Load(ctx, "default", iceberg.Properties{"type": "mycatalog", ...})` will route to the factory. Built-in types: `rest`, `hive`, `glue`, `sql`, `hadoop`.
+
+`catalog.GetRegisteredCatalogs()` returns the current list; `catalog.Unregister(catalogType)` removes one.
+
+### LocationProvider
+
+[`table/locations.go`](https://github.com/apache/iceberg-go/blob/main/table/locations.go) defines the `LocationProvider` interface and ships two implementations: `simpleLocationProvider` (default) and `objectStoreLocationProvider` (selected by `write.object-storage.enabled = true`). The provider is chosen by table properties and is not user-pluggable today.
+
+## Table write properties
+
+Property key constants are in [`table/properties.go`](https://github.com/apache/iceberg-go/blob/main/table/properties.go) and Parquet keys in [`table/internal/parquet_files.go`](https://github.com/apache/iceberg-go/blob/main/table/internal/parquet_files.go). The keys below have verified read sites in non-test code.
+
+### Format and file sizing
+
+| Key | Default | Description |
+|---|---|---|
+| `write.format.default` | `parquet` | File format used when writing data files. Read in `table/writer.go` and `table/rolling_data_writer.go`. |
+| `write.target-file-size-bytes` | (set by writer) | Target size for newly written data files. Read in `table/arrow_utils.go` and `table/equality_delete_writer.go`. |
+
+### Metrics and metadata lifecycle
+
+| Key | Description |
+|---|---|
+| `write.metadata.metrics.default` | Default per-column metrics mode. |
+| `write.metadata.metrics.column.<name>` | Per-column override prefix. |
+| `write.metadata.delete-after-commit.enabled` | When true, expire old metadata files after a successful commit. |
+| `write.metadata.previous-versions-max` | Cap on retained metadata files. Default `100`. |
+| `write.metadata.compression-codec` | Compression for metadata JSON. |
+
+### Manifest and commit
+
+| Key | Description |
+|---|---|
+| `commit.manifest-merge.enabled` | Merge small manifests during commit. |
+| `commit.manifest.target-size-bytes` | Target size for merged manifests. |
+| `commit.manifest.min-count-to-merge` | Minimum manifest count that triggers a merge. |
+| `commit.retry.num-retries` | Retries for `ErrCommitFailed`. |
+| `commit.retry.min-wait-ms` / `commit.retry.max-wait-ms` / `commit.retry.total-timeout-ms` | Backoff bounds. |
+
+### Snapshot retention
+
+| Key | Description |
+|---|---|
+| `min-snapshots-to-keep` | Minimum snapshots to retain when expiring. |
+| `max-snapshot-age-ms` | Maximum age of retained snapshots. |
+| `max-ref-age-ms` | Maximum age of branch/tag refs that are not the main branch. |
+| `gc.enabled` | Gate for orphan-file cleanup. |
+
+### Delete mode
+
+| Key | Description |
+|---|---|
+| `write.delete.mode` | Delete strategy used by row-level delete writers. |
+
+### Object-store data layout
+
+| Key | Description |
+|---|---|
+| `write.data.path` | Override data file directory. |
+| `write.metadata.path` | Override metadata file directory. |
+| `write.object-storage.enabled` | Switch the location provider to the hashed object-storage layout. |
+| `write.object-storage.partitioned-paths` | Whether partition values are included in object-storage paths. |
+
+### Parquet writer
+
+All defined in `table/internal/parquet_files.go` and read by the Parquet writer:
+
+| Key | Default |
+|---|---|
+| `write.parquet.row-group-size-bytes` | 128 MB |
+| `write.parquet.row-group-limit` | 1,048,576 rows |
+| `write.parquet.page-size-bytes` | 1 MB |
+| `write.parquet.page-row-limit` | 20,000 rows |
+| `write.parquet.dict-size-bytes` | 2 MB |
+| `write.parquet.page-version` | `2` |
+| `write.parquet.compression-codec` | `zstd` |
+| `write.parquet.compression-level` | `-1` (codec default) |
+| `write.parquet.bloom-filter-max-bytes` | 1 MB |
+| `write.parquet.bloom-filter-enabled.column.<name>` | (per-column toggle, prefix-matched) |
+
+### Parquet reader
+
+| Key | Description |
+|---|---|
+| `read.parquet.batch-size` | Arrow record-batch size used by the Parquet reader. |
diff --git a/website/src/SUMMARY.md b/website/src/contributing.md
similarity index 83%
copy from website/src/SUMMARY.md
copy to website/src/contributing.md
index 7d3934c8..dfd46301 100644
--- a/website/src/SUMMARY.md
+++ b/website/src/contributing.md
@@ -17,15 +17,4 @@
   ~ under the License.
 -->
 
-- [Introduction](./introduction.md)
-
-# User Guide
-
-- [Install](./install.md)
-- [CLI](./cli.md)
-- [API](./api.md)
-
-# Developer Guide
-
-- [Glossary](./glossary.md)
-
+{{#include ../../CONTRIBUTING.md:18:}}
diff --git a/website/src/ecosystem.md b/website/src/ecosystem.md
new file mode 100644
index 00000000..f773918b
--- /dev/null
+++ b/website/src/ecosystem.md
@@ -0,0 +1,43 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements.  See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership.  The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License.  You may obtain a copy of the License at
+  ~
+  ~   http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied.  See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+-->
+
+# Other Iceberg implementations
+
+Apache Iceberg Go is one of several official Iceberg implementations. Pick the one that matches your runtime; the table format and catalog protocols are the same across all of them.
+
+| Project | Language | Repository | Documentation |
+|---|---|---|---|
+| Apache Iceberg | Java (reference) | [apache/iceberg](https://github.com/apache/iceberg) | [iceberg.apache.org](https://iceberg.apache.org/) |
+| PyIceberg | Python | [apache/iceberg-python](https://github.com/apache/iceberg-python) | [py.iceberg.apache.org](https://py.iceberg.apache.org/) |
+| iceberg-rust | Rust | [apache/iceberg-rust](https://github.com/apache/iceberg-rust) | [rust.iceberg.apache.org](https://rust.iceberg.apache.org/) |
+| iceberg-cpp | C++ | [apache/iceberg-cpp](https://github.com/apache/iceberg-cpp) | [cpp.iceberg.apache.org](https://cpp.iceberg.apache.org/) (early stage) |
+
+## When to use which
+
+- **Java** is the reference implementation and is what every query engine integrates against (Spark, Flink, Trino, Hive, Presto, Dremio, etc.). If you are running a JVM workload, this is the canonical choice.
+- **PyIceberg** is for Python and the dataframe ecosystem (PyArrow, Pandas, Polars, DuckDB, Daft, Ray). Most data-science and ML workflows live here.
+- **iceberg-rust** is the Rust implementation, used by `pyiceberg-core`, DataFusion-based engines, and other Rust-native systems.
+- **iceberg-cpp** is early-stage (0.2.0 released 2026-01-26). Track the project for native C++ integration once it stabilizes.
+- **iceberg-go** (this project) is for Go services and tooling. Tight Apache Arrow Go integration makes it a good fit for streaming Arrow record batches into and out of Iceberg tables.
+
+## Specifications and shared concepts
+
+The Iceberg spec, terminology, partitioning semantics, evolution semantics, REST Catalog OpenAPI, and multi-engine support policy live with the main project at [iceberg.apache.org](https://iceberg.apache.org/). All the implementations above target the same spec.
+
+For Apache Iceberg Go-specific guidance, continue with the [API Reference](./api.md), [CLI](./cli.md), or [Configuration](./configuration.md).
diff --git a/website/src/expression-dsl.md b/website/src/expression-dsl.md
new file mode 100644
index 00000000..e5f50c06
--- /dev/null
+++ b/website/src/expression-dsl.md
@@ -0,0 +1,131 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements.  See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership.  The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License.  You may obtain a copy of the License at
+  ~
+  ~   http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied.  See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+-->
+
+# Expression DSL
+
+This page covers the building blocks behind the row-filter shortcuts in [Row Filter Syntax](./row-filter-syntax.md): boolean combinators, terms, and the lower-level predicate constructors.
+
+The DSL lives entirely in the root `iceberg` package (see `exprs.go` and `predicates.go`).
+
+## Boolean combinators
+
+```go
+iceberg.NewAnd(a, b)              // a AND b
+iceberg.NewAnd(a, b, c, d)        // a AND b AND c AND d (variadic)
+iceberg.NewOr(a, b)               // a OR b
+iceberg.NewOr(a, b, c, d)         // a OR b OR c OR d
+iceberg.NewNot(a)                 // NOT a
+```
+
+`NewAnd` and `NewOr` accept two required arguments plus a variadic tail (`exprs.go:226`, `exprs.go:287`). They simplify automatically:
+
+- `NewAnd(x, AlwaysTrue{})` reduces to `x`.
+- `NewAnd(x, AlwaysFalse{})` reduces to `AlwaysFalse{}`.
+- `NewOr(x, AlwaysFalse{})` reduces to `x`.
+- `NewOr(x, AlwaysTrue{})` reduces to `AlwaysTrue{}`.
+- `NewNot(NewNot(x))` reduces to `x`.
+
+## Constants
+
+```go
+iceberg.AlwaysTrue{}
+iceberg.AlwaysFalse{}
+```
+
+Both satisfy `BooleanExpression`. Use them as the identity element when composing filters dynamically.
+
+## Terms
+
+A *term* is the left-hand side of a predicate. Iceberg-go has two flavors:
+
+- `Reference("column_name")` - an unbound term that names a column (`exprs.go:373`). Typing happens at bind time, when the expression is matched against a schema. This is what you almost always want.
+- `BoundReference` - the resolved form, produced by `Reference.Bind(schema, caseSensitive)` (`exprs.go:389`). You only encounter these when writing custom expression visitors.
+
+The interfaces are:
+
+```go
+type Term interface { ... }                        // shared marker
+type UnboundTerm interface { Term; ... }           // pre-bind
+type BoundTerm interface { Term; Ref() BoundReference; ... }
+```
+
+(`exprs.go:317-348`)
+
+## Predicates
+
+A *predicate* applies an `Operation` to one or more terms. `BooleanExpression` is the shared interface (`exprs.go:123`).
+
+### Convenience builders (recommended)
+
+For all the common shapes, the constructors in `predicates.go` are the right tool. See [Row Filter Syntax](./row-filter-syntax.md) for the full list (`EqualTo`, `LessThan`, `IsIn`, `IsNull`, `StartsWith`, etc.).
+
+### Lower-level escape hatches
+
+When the convenience builders are not enough (custom operators, dynamic operation selection, working with already-typed `Literal` values), use the predicate constructors directly:
+
+```go
+// Unary predicates: IS NULL / NOT NULL / IS NaN / NOT NaN
+pred := iceberg.UnaryPredicate(iceberg.OpIsNull, iceberg.Reference("col"))
+
+// Literal predicates: <, <=, >, >=, ==, !=, STARTS WITH, NOT STARTS WITH
+lit := iceberg.NewLiteral(int64(42))
+pred := iceberg.LiteralPredicate(iceberg.OpEQ, iceberg.Reference("col"), lit)
+
+// Set predicates: IN / NOT IN
+lits := []iceberg.Literal{iceberg.NewLiteral("a"), iceberg.NewLiteral("b")}
+pred := iceberg.SetPredicate(iceberg.OpIn, iceberg.Reference("col"), lits)
+```
+
+`UnaryPredicate` lives at `exprs.go:534`. `LiteralPredicate` and `SetPredicate` live in the same file.
+
+## Negation
+
+Every `BooleanExpression` and every `Operation` knows how to negate itself.
+
+```go
+op := iceberg.OpEQ
+op.Negate()  // -> OpNEQ
+```
+
+(`exprs.go:65-98`. `OpNot`, `OpAnd`, and `OpOr` panic on direct negation - negate the wrapping expression instead.)
+
+```go
+expr := iceberg.EqualTo(iceberg.Reference("status"), "active")
+inverted := expr.Negate()  // equivalent to NotEqualTo(...)
+```
+
+## Binding and evaluation
+
+Most user code stops at constructing the unbound expression - the scan pipeline handles binding, projection, and evaluation internally. If you are writing a custom visitor:
+
+- `(Reference).Bind(schema, caseSensitive)` returns a `BoundTerm` (`exprs.go:389`).
+- `BoundExpression`s expose `Ref()`, `Type()`, and (for terms) the underlying `accessor` for evaluating against a `StructLike` row.
+
+For projection, evaluation, and visitor patterns, see `visitors.go` and the scan internals in `table/scanner.go`.
+
+## When to reach for what
+
+| Goal | Use |
+|---|---|
+| Filter a scan or row-level delete | Convenience builders + `NewAnd`/`NewOr`/`NewNot` |
+| Combine many clauses dynamically | Start from `AlwaysTrue{}` (for AND) or `AlwaysFalse{}` (for OR), fold with `NewAnd`/`NewOr` |
+| Construct a predicate whose operator is chosen at runtime | `UnaryPredicate(op, term)`, `LiteralPredicate(op, term, lit)`, `SetPredicate(op, term, lits)` |
+| Walk an expression tree | A custom `BooleanExprVisitor` from `visitors.go` |
+
+For the per-operator cookbook, return to [Row Filter Syntax](./row-filter-syntax.md).
diff --git a/website/src/feature-status.md b/website/src/feature-status.md
new file mode 100644
index 00000000..84718ee0
--- /dev/null
+++ b/website/src/feature-status.md
@@ -0,0 +1,131 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements.  See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership.  The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License.  You may obtain a copy of the License at
+  ~
+  ~   http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied.  See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+-->
+
+# Feature Status
+
+This page tracks what Apache Iceberg Go currently supports. The matrix is kept in sync with the project [`README.md`](https://github.com/apache/iceberg-go/blob/main/README.md); if you spot a discrepancy, file an issue.
+
+## Spec format version coverage
+
+Apache Iceberg Go reads and writes table format versions 1, 2, and 3. The maximum supported version is enforced at [`table/metadata.go`](https://github.com/apache/iceberg-go/blob/main/table/metadata.go) (`supportedTableFormatVersion = 3`). For active tracking, see issues [#589 (V3)](https://github.com/apache/iceberg-go/issues/589) and [#829 (V2 completion)](https://github.com/apache/iceberg-go/issues/829).
+
+### V1
+
+All V1 features are supported. V1 is the format-version baseline.
+
+### V2
+
+| Feature | Status |
+|---|---|
+| Sequence numbers | Supported |
+| Manifest entry status (added / existing / deleted) | Supported |
+| Positional deletes | Supported (read + write) |
+| Equality deletes | Supported (read + write). Write via `Transaction.WriteEqualityDeletes`; row-level commits via `Transaction.NewRowDelta` |
+| Partition spec evolution | Supported |
+| Sort order enforcement on write | Supported (PR [#1157](https://github.com/apache/iceberg-go/pull/1157), closes [#833](https://github.com/apache/iceberg-go/issues/833)) |
+| `ReplaceDataFiles` using `OpReplace` | Pending ([#841](https://github.com/apache/iceberg-go/issues/841)) |
+
+### V3
+
+| Feature | Status |
+|---|---|
+| Nanosecond timestamps (`timestamp_ns`, `timestamptz_ns`) | Supported |
+| Default values (`initial-default`, `write-default`) | Supported |
+| Row lineage (`_row_id`, `_last_updated_sequence_number`) | Supported |
+| Encryption keys in metadata | Supported |
+| Variant type, non-shredded | Supported (PR [#932](https://github.com/apache/iceberg-go/pull/932); umbrella [#929](https://github.com/apache/iceberg-go/issues/929)) |
+| Variant type, shredded reader / writer | In progress ([#986](https://github.com/apache/iceberg-go/issues/986), [#987](https://github.com/apache/iceberg-go/issues/987)) |
+| Deletion vectors, read | Supported |
+| Deletion vectors, write (unpartitioned) | Supported |
+| Deletion vectors, write (partitioned) | In progress ([#1135](https://github.com/apache/iceberg-go/issues/1135), PR [#1151](https://github.com/apache/iceberg-go/pull/1151)) |
+| Geometry / Geography types (schema) | Supported |
+| Geometry / Geography (transforms, statistics, pruning) | In progress (umbrella [#989](https://github.com/apache/iceberg-go/issues/989)) |
+| Multi-argument transforms | Infrastructure present; no concrete implementations exercised yet |
+
+## FileSystem support
+
+| Filesystem Type      | Supported |
+| :------------------: | :-------: |
+| S3                   |    X      |
+| Google Cloud Storage |    X      |
+| Azure Blob Storage   |    X      |
+| Local Filesystem     |    X      |
+
+S3, GCS, and Azure require a blank import: `_ "github.com/apache/iceberg-go/io/gocloud"`. See [Configuration](./configuration.md).
+
+## Metadata operations
+
+| Operation                | Supported |
+| :----------------------- | :-------: |
+| Get Schema               |     X     |
+| Get Snapshots            |     X     |
+| Get Sort Orders          |     X     |
+| Get Partition Specs      |     X     |
+| Get Manifests            |     X     |
+| Create New Manifests     |     X     |
+| Plan Scan                |     X     |
+| Plan Scan for Snapshot   |     X     |
+
+## Catalog support
+
+| Operation                   | REST | Hive |  Glue  | SQL  | Hadoop |
+|:----------------------------|:----:|:----:|:------:|:----:|:------:|
+| Load Table                  |  X   |  X   |   X    |  X   |   X    |
+| List Tables                 |  X   |  X   |   X    |  X   |   X    |
+| Create Table                |  X   |  X   |   X    |  X   |   X    |
+| Register Table              |  X   |  X   |   X    |      |        |
+| Update Current Snapshot     |  X   |  X   |   X    |  X   |   X    |
+| Create New Snapshot         |  X   |  X   |   X    |  X   |   X    |
+| Rename Table                |  X   |  X   |   X    |  X   |        |
+| Drop Table                  |  X   |  X   |   X    |  X   |   X    |
+| Alter Table                 |  X   |  X   |   X    |  X   |   X    |
+| Check Table Exists          |  X   |  X   |   X    |  X   |   X    |
+| Set Table Properties        |  X   |  X   |   X    |  X   |   X    |
+| List Namespaces             |  X   |  X   |   X    |  X   |   X    |
+| Create Namespace            |  X   |  X   |   X    |  X   |   X    |
+| Check Namespace Exists      |  X   |  X   |   X    |  X   |   X    |
+| Drop Namespace              |  X   |  X   |   X    |  X   |   X    |
+| Update Namespace Properties |  X   |  X   |   X    |  X   |        |
+| Create View                 |  X   |  X   |        |  X   |        |
+| Load View                   |      |  X   |        |  X   |        |
+| List View                   |  X   |  X   |        |  X   |        |
+| Drop View                   |  X   |  X   |        |  X   |        |
+| Check View Exists           |  X   |  X   |        |  X   |        |
+
+A Hadoop catalog is also available - see [`catalog/hadoop`](https://github.com/apache/iceberg-go/tree/main/catalog/hadoop).
+
+## Read / write data
+
+Data can be read as an Arrow `Table` or as a stream of Arrow record batches via `iter.Seq2`. See [API Reference](./api.md).
+
+### Supported write operations
+
+As long as the FileSystem is supported and the Catalog supports altering the table:
+
+| Operation            | Supported |
+|:---------------------|:---------:|
+| Append Stream        |     X     |
+| Append Data Files    |     X     |
+| Rewrite Files        |     X     |
+| Rewrite manifests    |           |
+| Overwrite Files      |     X     |
+| Copy-On-Write Delete |     X     |
+| Write Pos Delete     |     X     |
+| Write Eq Delete      |     X     |
+| Row Delta            |     X     |
diff --git a/website/src/getting-started.md b/website/src/getting-started.md
new file mode 100644
index 00000000..e2ed1db5
--- /dev/null
+++ b/website/src/getting-started.md
@@ -0,0 +1,255 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements.  See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership.  The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License.  You may obtain a copy of the License at
+  ~
+  ~   http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied.  See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+-->
+
+# Getting Started
+
+This walkthrough takes you from `go get` to a fully written-and-read Iceberg table in a few minutes, using a local SQLite-backed catalog so you do not need any external services. By the end you will have:
+
+- An Iceberg catalog stored in a SQLite file
+- A table with an Arrow schema
+- Data written from Apache Arrow Go and read back
+- A schema evolution committed
+- A branch created on top of the table
+
+If you would rather see all the operations as a reference, jump straight to the [API](./api.md).
+
+## 1. Install
+
+```sh
+go mod init iceberg-go-tutorial
+go get github.com/apache/iceberg-go@latest
+go get github.com/apache/arrow-go/v18@latest
+go get github.com/uptrace/bun/driver/sqliteshim@latest
+```
+
+`iceberg-go` itself only registers the local file system. For S3, GCS, or Azure Blob you would also blank-import `github.com/apache/iceberg-go/io/gocloud`. We are staying on local disk for this tutorial.
+
+## 2. Open a local catalog
+
+The SQL catalog stores its metadata in a database, and the actual data files live under a "warehouse" directory. We will use SQLite for both the catalog DB and a local folder for the warehouse.
+
+```go
+package main
+
+import (
+    "context"
+    "database/sql"
+    "log"
+
+    "github.com/apache/iceberg-go"
+    sqlcat "github.com/apache/iceberg-go/catalog/sql"
+    "github.com/uptrace/bun/driver/sqliteshim"
+)
+
+func openCatalog(ctx context.Context) (*sqlcat.Catalog, error) {
+    db, err := sql.Open(sqliteshim.ShimName, "file:./tutorial-catalog.db?cache=shared")
+    if err != nil {
+        return nil, err
+    }
+    return sqlcat.NewCatalog("default", db, sqlcat.SQLite, iceberg.Properties{
+        "warehouse":            "file:///tmp/iceberg-tutorial",
+        "init_catalog_tables":  "true",
+    })
+}
+```
+
+`init_catalog_tables: "true"` lets the catalog create its bookkeeping tables (`iceberg_tables`, `iceberg_namespace_properties`) on first use. Make sure `/tmp/iceberg-tutorial` is writable.
+
+## 3. Create a namespace and a table
+
+Iceberg organizes tables under namespaces (the analog of databases). We will create one and put a table inside it.
+
+```go
+import (
+    "github.com/apache/iceberg-go/catalog"
+    "github.com/apache/iceberg-go/table"
+)
+
+func createTrips(ctx context.Context, cat *sqlcat.Catalog) (*table.Table, error) {
+    ns := table.Identifier{"taxi"}
+    if err := cat.CreateNamespace(ctx, ns, nil); err != nil {
+        return nil, err
+    }
+
+    schema := iceberg.NewSchema(1,
+        iceberg.NestedField{ID: 1, Name: "trip_id", Type: iceberg.PrimitiveTypes.Int64, Required: true},
+        iceberg.NestedField{ID: 2, Name: "fare", Type: iceberg.PrimitiveTypes.Float64, Required: false},
+        iceberg.NestedField{ID: 3, Name: "borough", Type: iceberg.PrimitiveTypes.String, Required: false},
+    )
+
+    ident := catalog.ToIdentifier("taxi", "trips")
+    return cat.CreateTable(ctx, ident, schema)
+}
+```
+
+If the namespace already exists, `CreateNamespace` returns an error - the example skips error handling for brevity; production code should check for `iceberg.ErrAlreadyExists` and recover.
+
+## 4. Write some Arrow data
+
+The write path takes either a streaming [`array.RecordReader`](https://pkg.go.dev/github.com/apache/arrow-go/v18/arrow/array#RecordReader) or a fully materialized [`arrow.Table`](https://pkg.go.dev/github.com/apache/arrow-go/v18/arrow#Table). We will build a small Arrow table inline and append it.
+
+```go
+import (
+    "github.com/apache/arrow-go/v18/arrow"
+    "github.com/apache/arrow-go/v18/arrow/array"
+    "github.com/apache/arrow-go/v18/arrow/memory"
+)
+
+func writeSomeTrips(ctx context.Context, tbl *table.Table) (*table.Table, error) {
+    mem := memory.NewGoAllocator()
+
+    arrowSchema := arrow.NewSchema([]arrow.Field{
+        {Name: "trip_id", Type: arrow.PrimitiveTypes.Int64, Nullable: false},
+        {Name: "fare", Type: arrow.PrimitiveTypes.Float64, Nullable: true},
+        {Name: "borough", Type: arrow.BinaryTypes.String, Nullable: true},
+    }, nil)
+
+    b := array.NewRecordBuilder(mem, arrowSchema)
+    defer b.Release()
+
+    b.Field(0).(*array.Int64Builder).AppendValues([]int64{1, 2, 3}, nil)
+    b.Field(1).(*array.Float64Builder).AppendValues([]float64{12.50, 8.75, 22.10}, nil)
+    b.Field(2).(*array.StringBuilder).AppendValues([]string{"Manhattan", "Brooklyn", "Queens"}, nil)
+
+    rec := b.NewRecord()
+    defer rec.Release()
+
+    arrowTbl := array.NewTableFromRecords(arrowSchema, []arrow.Record{rec})
+    defer arrowTbl.Release()
+
+    return tbl.AppendTable(ctx, arrowTbl, 1024 /* batchSize */, nil)
+}
+```
+
+`AppendTable` returns a refreshed `*table.Table` reflecting the new snapshot.
+
+## 5. Read the data back
+
+```go
+func readAll(ctx context.Context, tbl *table.Table) error {
+    arrowTbl, err := tbl.Scan().ToArrowTable(ctx)
+    if err != nil {
+        return err
+    }
+    defer arrowTbl.Release()
+
+    log.Printf("read %d rows in %d columns", arrowTbl.NumRows(), arrowTbl.NumCols())
+    return nil
+}
+```
+
+For larger tables, use streaming so only one batch is in memory at a time:
+
+```go
+arrowSchema, batches, err := tbl.Scan().ToArrowRecords(ctx)
+if err != nil {
+    return err
+}
+log.Printf("scan schema: %s", arrowSchema)
+
+for batch, err := range batches {
+    if err != nil {
+        return err
+    }
+    log.Printf("batch with %d rows", batch.NumRows())
+    batch.Release()
+}
+```
+
+## 6. Filter and project
+
+Use the [predicate DSL](./row-filter-syntax.md) to push filters down into the scan, and `WithSelectedFields` to project columns:
+
+```go
+filter := iceberg.GreaterThan(iceberg.Reference("fare"), float64(10.0))
+
+arrowTbl, err := tbl.Scan(
+    table.WithSelectedFields("trip_id", "fare"),
+    table.WithRowFilter(filter),
+).ToArrowTable(ctx)
+```
+
+## 7. Evolve the schema
+
+Most schema changes go through a transaction. Add a `tip` column:
+
+```go
+import "github.com/apache/iceberg-go/table"
+
+func addTipColumn(ctx context.Context, tbl *table.Table) (*table.Table, error) {
+    txn := tbl.NewTransaction()
+
+    err := table.NewUpdateSchema(txn, true /* caseSensitive */, false /* allowIncompatible */).
+        AddColumn([]string{"tip"}, iceberg.PrimitiveTypes.Float64, "Tip in dollars", false, nil).
+        Commit()
+    if err != nil {
+        return nil, err
+    }
+
+    return txn.Commit(ctx)
+}
+```
+
+The returned table has the new schema and a fresh metadata file.
+
+## 8. Branch the table
+
+A branch is a named ref that points at a snapshot. Creating one requires a metadata commit that adds the ref - `NewTransactionOnBranch` only writes to a branch that already exists. Two steps:
+
+```go
+import "github.com/apache/iceberg-go/table"
+
+// Step 1: create the branch via Catalog.CommitTable.
+func createExperimentBranch(ctx context.Context, cat *sqlcat.Catalog, tbl *table.Table) (*table.Table, error) {
+    snap := tbl.CurrentSnapshot()
+    update := table.NewSetSnapshotRefUpdate(
+        "experiment", snap.SnapshotID, table.BranchRef,
+        0 /* maxRefAgeMs */, 0 /* maxSnapshotAgeMs */, 0 /* minSnapshotsToKeep */,
+    )
+    reqs := []table.Requirement{
+        table.AssertTableUUID(tbl.Metadata().TableUUID()),
+        table.AssertRefSnapshotID("experiment", nil), // branch must not yet exist
+    }
+    if _, _, err := cat.CommitTable(ctx, tbl.Identifier(), reqs, []table.Update{update}); err != nil {
+        return nil, err
+    }
+    // Reload so subsequent transactions see the new ref.
+    return cat.LoadTable(ctx, tbl.Identifier())
+}
+
+// Step 2: open a transaction on the branch and write.
+func writeOnBranch(ctx context.Context, tbl *table.Table, arrowTbl arrow.Table) (*table.Table, error) {
+    txn := tbl.NewTransactionOnBranch("experiment")
+    if err := txn.AppendTable(ctx, arrowTbl, 1024, nil); err != nil {
+        return nil, err
+    }
+    return txn.Commit(ctx)
+}
+```
+
+Reads can target the branch with `tbl.Scan().UseRef("experiment")`.
+
+## Where to go next
+
+- [API](./api.md) - the full Go surface for catalogs, tables, scans, writes, transactions, schema and partition evolution, snapshot management, maintenance, and views.
+- [Configuration](./configuration.md) - cloud credentials, table properties, concurrency, custom catalog and IO registration.
+- [CLI](./cli.md) - inspect, expire, compact, branch, and tag from the command line.
+- [Row Filter Syntax](./row-filter-syntax.md) and [Expression DSL](./expression-dsl.md) - the predicate DSL in detail.
+
+The full Iceberg specification, terminology, and engine integration policy live with the main project at [iceberg.apache.org](https://iceberg.apache.org/).
diff --git a/website/src/how-to-release.md b/website/src/how-to-release.md
new file mode 100644
index 00000000..03785962
--- /dev/null
+++ b/website/src/how-to-release.md
@@ -0,0 +1,93 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements.  See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership.  The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License.  You may obtain a copy of the License at
+  ~
+  ~   http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied.  See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+-->
+
+# How to release
+
+This page is for Apache Iceberg PMC members and committers who are cutting a new Apache Iceberg Go release. The canonical scripts live in [`dev/release/`](https://github.com/apache/iceberg-go/tree/main/dev/release) and `dev/release/README.md` is the source of truth - this page mirrors it and adds context.
+
+## Requirements
+
+- You must be an Apache Iceberg committer or PMC member.
+- You must prepare a PGP key for signing. See [https://infra.apache.org/release-signing.html#generate](https://infra.apache.org/release-signing.html#generate).
+- Your PGP key must be registered in the Apache Iceberg `KEYS` file at `https://downloads.apache.org/iceberg/KEYS`. To add a key:
+
+  ```sh
+  svn co https://dist.apache.org/repos/dist/release/iceberg
+  cd iceberg
+  $EDITOR KEYS
+  svn ci KEYS
+  ```
+
+- You must run the release scripts from a working copy whose `origin` remote is `git@github.com:apache/iceberg-go.git` (not your fork). `release_rc.sh` enforces this.
+
+## Overview
+
+1. Test the revision to be released.
+2. Prepare an RC and start a vote.
+3. On a passing vote, publish.
+
+## Prepare an RC and vote
+
+Run `dev/release/release_rc.sh` against the canonical clone:
+
+```sh
+git clone git@github.com:apache/iceberg-go.git
+cd iceberg-go
+GH_TOKEN=${YOUR_GITHUB_TOKEN} dev/release/release_rc.sh ${VERSION} ${RC}
+```
+
+Example for `0.6.0` RC1:
+
+```sh
+GH_TOKEN=${YOUR_GITHUB_TOKEN} dev/release/release_rc.sh 0.6.0 1
+```
+
+The arguments are the version and the RC number. If `RC1` has a problem, increment the RC number to `RC2`, `RC3`, and so on.
+
+`release_rc.sh` will:
+
+- Tag `vX.Y.Z-rc<N>` and push the tag.
+- Create a signed source tarball.
+- Upload the artifacts to `https://dist.apache.org/repos/dist/dev/iceberg/`.
+- Print a draft `[VOTE]` email you can use on `dev@iceberg.apache.org`.
+
+Send the `[VOTE]` email. The vote runs for at least 72 hours and requires three +1 votes from PMC members with no -1 votes to pass.
+
+## Publish
+
+When the vote passes, run:
+
+```sh
+GH_TOKEN=${YOUR_GITHUB_TOKEN} dev/release/release.sh ${VERSION} ${RC}
+```
+
+`release.sh` moves the artifacts from `https://dist.apache.org/repos/dist/dev/iceberg/` to `https://dist.apache.org/repos/dist/release/iceberg/` (which feeds `https://downloads.apache.org/iceberg/`) and creates a GitHub Release with auto-generated notes.
+
+## Post-release tasks
+
+After publishing, complete these steps:
+
+1. Add the release to ASF's report database at the [Apache Committee Report Helper](https://reporter.apache.org/addrelease.html?iceberg).
+2. Verify the GitHub Release at `https://github.com/apache/iceberg-go/releases` is correctly tagged, has generated release notes against the prior tag, and is marked as latest. `release.sh` runs `gh release create ... --generate-notes --verify-tag` so the release should already exist; double-check the notes and the "Latest" badge.
+3. Send the `[ANNOUNCE]` email to `dev@iceberg.apache.org` and `announce@apache.org`.
+4. File a release blog post in [`apache/iceberg`](https://github.com/apache/iceberg) under `site/docs/blog/posts/`. See the prior 0.5.0 post (`2026-03-05-iceberg-go-0.5.0-release.md`) for the frontmatter and structure.
+
+## Patch releases
+
+`dev/release/README.md` does not document a patch-branch convention (e.g. `iceberg-go-0.X.x`). Confirm with the PMC on `dev@iceberg.apache.org` before cutting a patch release.
diff --git a/website/src/introduction.md b/website/src/introduction.md
index 1c2353e9..80ac5b9b 100644
--- a/website/src/introduction.md
+++ b/website/src/introduction.md
@@ -19,86 +19,29 @@
 
 # Iceberg Go
 
-Iceberg Go is a go-native implementation for accessing iceberg tables.
+Apache Iceberg Go is a Go-native implementation of [Apache Iceberg](https://iceberg.apache.org/), the open table format for analytic datasets. Read and write Iceberg tables from Go services and tooling without a JVM.
 
 [![Go Reference](https://pkg.go.dev/badge/github.com/apache/iceberg-go.svg)](https://pkg.go.dev/github.com/apache/iceberg-go)
 
-`iceberg` is a Golang implementation of the [Iceberg table spec](https://iceberg.apache.org/spec/).
+## Where to start
 
+- **[Install](./install.md)** - get the library and CLI on your machine.
+- **[CLI](./cli.md)** - inspect tables, run maintenance, manage refs.
+- **[API](./api.md)** - construct catalogs, scan tables, write Arrow data, evolve schemas.
+- **[Configuration](./configuration.md)** - YAML config file, catalog options, FileIO and credentials, table properties.
 
-## Feature Support / Roadmap
+## What works today
 
-### FileSystem Support
+A capability matrix - filesystem, metadata operations, catalog support, and write operations - lives on the dedicated **[Feature Status](./feature-status.md)** page.
 
-| Filesystem Type      | Supported |
-| :------------------: | :-------: |
-| S3                   |    X      |
-| Google Cloud Storage |    X      |
-| Azure Blob Storage   |    X      |
-| Local Filesystem     |    X      |
+## Beyond Go
 
-### Metadata
+Apache Iceberg is multi-language. PyIceberg, iceberg-rust, iceberg-cpp, and the Java reference implementation all target the same spec - see **[Other Iceberg implementations](./ecosystem.md)** for cross-links.
 
-| Operation                | Supported |
-| :----------------------- | :-------: |
-| Get Schema               |     X     |
-| Get Snapshots            |     X     |
-| Get Sort Orders          |     X     |
-| Get Partition Specs      |     X     |
-| Get Manifests            |     X     |
-| Create New Manifests     |     X     |
-| Plan Scan                |     X     |
-| Plan Scan for Snapshot   |     X     |
+## Help and contribution
 
-### Catalog Support
+- Questions and discussion: **[Community](./community.md)**
+- Contributing code or docs: **[Contributing](./contributing.md)**
+- Cutting or verifying a release: **[Releases](./releases.md)**
 
-| Operation                   | REST | Hive |  Glue  | SQL  |
-|:----------------------------|:----:|:----:|:------:|:----:|
-| Load Table                  |  X   |  X   |   X    |  X   |
-| List Tables                 |  X   |  X   |   X    |  X   |
-| Create Table                |  X   |  X   |   X    |  X   |
-| Register Table              |  X   |  X   |   X    |      |
-| Update Current Snapshot     |  X   |  X   |   X    |  X   |
-| Create New Snapshot         |  X   |  X   |   X    |  X   |
-| Rename Table                |  X   |  X   |   X    |  X   |
-| Drop Table                  |  X   |  X   |   X    |  X   |
-| Alter Table                 |  X   |  X   |   X    |  X   |
-| Check Table Exists          |  X   |  X   |   X    |  X   |
-| Set Table Properties        |  X   |  X   |   X    |  X   |
-| List Namespaces             |  X   |  X   |   X    |  X   |
-| Create Namespace            |  X   |  X   |   X    |  X   |
-| Check Namespace Exists      |  X   |  X   |   X    |  X   |
-| Drop Namespace              |  X   |  X   |   X    |  X   |
-| Update Namespace Properties |  X   |  X   |   X    |  X   |
-| Create View                 |  X   |  X   |        |  X   |
-| Load View                   |      |  X   |        |  X   |
-| List View                   |  X   |  X   |        |  X   |
-| Drop View                   |  X   |  X   |        |  X   |
-| Check View Exists           |  X   |  X   |        |  X   |
-
-### Read/Write Data Support
-
-* Data can currently be read as an Arrow Table or as a stream of Arrow record batches.
-
-#### Supported Write Operations
-
-As long as the FileSystem is supported and the Catalog supports altering
-the table, the following tracks the current write support:
-
-| Operation            | Supported |
-|:---------------------|:---------:|
-| Append Stream        |     X     |
-| Append Data Files    |     X     |
-| Rewrite Files        |           |
-| Rewrite manifests    |           |
-| Overwrite Files      |     X     |
-| Copy-On-Write Delete |     X     |
-| Write Pos Delete     |     X     |
-| Write Eq Delete      |           |
-| Row Delta            |           |
-
-
-## Get in Touch
-
-- [Iceberg community](https://iceberg.apache.org/community/)
-- [Iceberg-Go Slack](https://apache-iceberg.slack.com/archives/C05J3MJ42BD)
\ No newline at end of file
+The canonical Iceberg specification, terminology, and multi-engine policy live with the main project at [iceberg.apache.org](https://iceberg.apache.org/). This site covers what is specific to the Go implementation.
diff --git a/website/src/releases.md b/website/src/releases.md
new file mode 100644
index 00000000..c9f97842
--- /dev/null
+++ b/website/src/releases.md
@@ -0,0 +1,48 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements.  See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership.  The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License.  You may obtain a copy of the License at
+  ~
+  ~   http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied.  See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+-->
+
+# Releases
+
+Apache Iceberg Go follows the standard Apache release process. Releases are cut from `main`, voted on by the Apache Iceberg PMC, and published as signed source tarballs to `https://downloads.apache.org/iceberg/` and as Go module versions tagged `vX.Y.Z`.
+
+## Latest release
+
+- [Latest release on GitHub](https://github.com/apache/iceberg-go/releases/latest)
+- All releases: [github.com/apache/iceberg-go/releases](https://github.com/apache/iceberg-go/releases)
+
+## Using a release
+
+Pin a tagged version directly with Go modules:
+
+```sh
+go get github.com/apache/iceberg-go@vX.Y.Z
+```
+
+To track `main`, use `@main` instead of a version tag.
+
+## Release notes
+
+Per-release notes (highlights, breaking changes, contributors) are published on the [GitHub Releases page](https://github.com/apache/iceberg-go/releases). Iceberg Go does not maintain a curated `CHANGELOG.md` in the repository; the GitHub Releases page is the canonical source.
+
+## Verifying and producing releases
+
+If you are validating an RC or cutting a new release, see:
+
+- [Verify a release](./verify-release.md) - what to do when a `[VOTE]` thread is posted on `dev@iceberg.apache.org`.
+- [How to release](./how-to-release.md) - PMC/committer process for cutting an RC and publishing.
diff --git a/website/src/row-filter-syntax.md b/website/src/row-filter-syntax.md
new file mode 100644
index 00000000..ccb2490f
--- /dev/null
+++ b/website/src/row-filter-syntax.md
@@ -0,0 +1,143 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements.  See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership.  The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License.  You may obtain a copy of the License at
+  ~
+  ~   http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied.  See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+-->
+
+# Row Filter Syntax
+
+Row filters drive predicate pushdown during scans, partition pruning, and row-level deletes. The DSL lives in the root `iceberg` package - all you need is the import:
+
+```go
+import "github.com/apache/iceberg-go"
+```
+
+A column is referenced with `iceberg.Reference("column_name")`. Predicate constructors return a `BooleanExpression` (or an `UnboundPredicate`, which satisfies `BooleanExpression`) that can be combined with the boolean combinators in the [Expression DSL](./expression-dsl.md) and passed to APIs like `table.WithRowFilter(...)`.
+
+## Equality
+
+```go
+iceberg.EqualTo(iceberg.Reference("status"), "active")
+iceberg.NotEqualTo(iceberg.Reference("retries"), int32(0))
+```
+
+`EqualTo[T]` and `NotEqualTo[T]` are generic over `LiteralType` (`bool`, `int32`, `int64`, `float32`, `float64`, `string`, `[]byte`, plus a few iceberg-specific types). The value's type must be in that set - bare `int` literals are not, so use `int32(0)` / `int64(0)` explicitly. They wrap `LiteralPredicate(OpEQ, ...)` and `LiteralPredicate(OpNEQ, ...)` (`predicates.go:83-91`).
+
+## Comparison
+
+```go
+iceberg.LessThan(iceberg.Reference("amount"), 100.0)
+iceberg.LessThanEqual(iceberg.Reference("amount"), 100.0)
+iceberg.GreaterThan(iceberg.Reference("created_at"), int64(1700000000))
+iceberg.GreaterThanEqual(iceberg.Reference("score"), int32(50))
+```
+
+Operators: `OpLT`, `OpLTEQ`, `OpGT`, `OpGTEQ` (`exprs.go:47-50`). Constructors at `predicates.go:98-124`.
+
+## Set membership
+
+```go
+iceberg.IsIn(iceberg.Reference("region"), "us-east", "us-west", "eu-west")
+iceberg.NotIn(iceberg.Reference("status"), "deleted", "archived")
+```
+
+`IsIn` and `NotIn` are variadic. They return a `BooleanExpression` (not `UnboundPredicate`) because the result can simplify automatically:
+
+- Zero values - reduces to `AlwaysFalse{}` (for `IsIn`) or `AlwaysTrue{}` (for `NotIn`).
+- One value - reduces to `EqualTo` / `NotEqualTo`.
+
+See `predicates.go:55-78`.
+
+## Null checks
+
+```go
+iceberg.IsNull(iceberg.Reference("deleted_at"))
+iceberg.NotNull(iceberg.Reference("user_id"))
+```
+
+These wrap `UnaryPredicate(OpIsNull, ...)` and `UnaryPredicate(OpNotNull, ...)`. Both panic if the term is `nil` (`predicates.go:23-32`).
+
+## NaN checks (float / double columns only)
+
+```go
+iceberg.IsNaN(iceberg.Reference("ratio"))
+iceberg.NotNaN(iceberg.Reference("ratio"))
+```
+
+Operators `OpIsNan` and `OpNotNan`. Use these instead of `EqualTo(..., math.NaN())` - NaN is never equal to itself.
+
+## String prefix
+
+```go
+iceberg.StartsWith(iceberg.Reference("path"), "/var/log/")
+iceberg.NotStartsWith(iceberg.Reference("name"), "tmp_")
+```
+
+Operators `OpStartsWith` and `OpNotStartsWith` (`exprs.go:53-54`). The value must be a `string`.
+
+## Constants
+
+```go
+iceberg.AlwaysTrue{}
+iceberg.AlwaysFalse{}
+```
+
+These satisfy `BooleanExpression` and short-circuit during expression simplification. Useful as a base case when filters are built dynamically:
+
+```go
+filter := iceberg.BooleanExpression(iceberg.AlwaysTrue{})
+for _, clause := range userClauses {
+    filter = iceberg.NewAnd(filter, clause)
+}
+```
+
+## Operator reference
+
+The full operator set is the `Operation` enum at `exprs.go:34-62`:
+
+| Operator | Constant | Convenience builder |
+|---|---|---|
+| `<` | `OpLT` | `LessThan` |
+| `<=` | `OpLTEQ` | `LessThanEqual` |
+| `>` | `OpGT` | `GreaterThan` |
+| `>=` | `OpGTEQ` | `GreaterThanEqual` |
+| `==` | `OpEQ` | `EqualTo` |
+| `!=` | `OpNEQ` | `NotEqualTo` |
+| `IS NULL` | `OpIsNull` | `IsNull` |
+| `IS NOT NULL` | `OpNotNull` | `NotNull` |
+| `IS NaN` | `OpIsNan` | `IsNaN` |
+| `IS NOT NaN` | `OpNotNan` | `NotNaN` |
+| `IN` | `OpIn` | `IsIn` |
+| `NOT IN` | `OpNotIn` | `NotIn` |
+| `STARTS WITH` | `OpStartsWith` | `StartsWith` |
+| `NOT STARTS WITH` | `OpNotStartsWith` | `NotStartsWith` |
+| `AND` / `OR` / `NOT` | `OpAnd` / `OpOr` / `OpNot` | `NewAnd` / `NewOr` / `NewNot` (see [Expression DSL](./expression-dsl.md)) |
+
+## Putting it together
+
+A typical filter passed to a scan:
+
+```go
+filter := iceberg.NewAnd(
+    iceberg.GreaterThanEqual(iceberg.Reference("event_time"), int64(1700000000)),
+    iceberg.IsIn(iceberg.Reference("region"), "us-east", "us-west"),
+    iceberg.NotNull(iceberg.Reference("user_id")),
+)
+
+scan := tbl.Scan(table.WithRowFilter(filter))
+```
+
+For boolean combination, term details, and the lower-level escape hatches (`UnaryPredicate`, `LiteralPredicate`, `SetPredicate`), see [Expression DSL](./expression-dsl.md).
diff --git a/website/src/verify-release.md b/website/src/verify-release.md
new file mode 100644
index 00000000..87343d77
--- /dev/null
+++ b/website/src/verify-release.md
@@ -0,0 +1,104 @@
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements.  See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership.  The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License.  You may obtain a copy of the License at
+  ~
+  ~   http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied.  See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+-->
+
+# Verify a release
+
+When a release candidate is announced on `dev@iceberg.apache.org`, anyone (committer or not) can help by verifying the artifacts. Verification is required from at least three Apache Iceberg PMC members for the vote to pass.
+
+The repository ships a script that performs the full verification end-to-end: `dev/release/verify_rc.sh`.
+
+## What an RC announcement contains
+
+A `[VOTE] iceberg-go X.Y.Z RC<N>` thread on `dev@iceberg.apache.org` will reference:
+
+- A signed source tarball under `https://dist.apache.org/repos/dist/dev/iceberg/apache-iceberg-go-${VERSION}-rc${RC}/` (`.tar.gz`, `.tar.gz.asc`, `.tar.gz.sha512`)
+- The Apache Iceberg `KEYS` file at `https://downloads.apache.org/iceberg/KEYS`
+- A GitHub compare URL between the previous release tag and the new RC tag
+
+## Prerequisites
+
+The script requires:
+
+- `curl`
+- `gpg`
+- `shasum` or `sha512sum`
+- `tar`
+
+You do not need Go installed - if Go is not on the system, the latest Go is downloaded automatically and used only for verification.
+
+## Import the Apache Iceberg KEYS
+
+```sh
+curl https://downloads.apache.org/iceberg/KEYS -o KEYS
+gpg --import KEYS
+```
+
+## Run the verification script
+
+The script takes the version and RC number as positional arguments:
+
+```sh
+dev/release/verify_rc.sh ${VERSION} ${RC}
+```
+
+For example, to verify `0.6.0` RC1:
+
+```sh
+dev/release/verify_rc.sh 0.6.0 1
+```
+
+If the verification succeeds, the script prints:
+
+```
+RC looks good!
+```
+
+## Optional environment variables
+
+`verify_rc.sh` honors these environment variables (all optional):
+
+| Variable | Default | Effect |
+|---|---|---|
+| `VERIFY_DEFAULT` | `1` | Master switch propagated to `VERIFY_DOWNLOAD` and `VERIFY_SIGN` if they are unset. |
+| `VERIFY_DOWNLOAD` | `${VERIFY_DEFAULT}` | Re-download artifacts when `1`; reuse the local copy when `0`. |
+| `VERIFY_SIGN` | `${VERIFY_DEFAULT}` | Re-run signature and checksum verification when `1`. |
+| `VERIFY_FORCE_USE_GO_BINARY` | `0` | When `1`, ignore any system Go and use the script's auto-downloaded Go. |
+| `GITHUB_TOKEN` | unset | Optional - supplies authenticated requests when fetching the latest Go release, avoiding rate limits. |
+
+## Manual verification fallback
+
+If you would rather verify by hand, the underlying steps are:
+
+```sh
+# Download the artifacts
+curl -O https://dist.apache.org/repos/dist/dev/iceberg/apache-iceberg-go-${VERSION}-rc${RC}/apache-iceberg-go-${VERSION}.tar.gz
+curl -O https://dist.apache.org/repos/dist/dev/iceberg/apache-iceberg-go-${VERSION}-rc${RC}/apache-iceberg-go-${VERSION}.tar.gz.asc
+curl -O https://dist.apache.org/repos/dist/dev/iceberg/apache-iceberg-go-${VERSION}-rc${RC}/apache-iceberg-go-${VERSION}.tar.gz.sha512
+
+# Verify the signature
+gpg --verify apache-iceberg-go-${VERSION}.tar.gz.asc apache-iceberg-go-${VERSION}.tar.gz
+
+# Verify the checksum (or sha512sum -c on systems without shasum)
+shasum -a 512 --check apache-iceberg-go-${VERSION}.tar.gz.sha512
+
+# Inspect the contents
+tar xf apache-iceberg-go-${VERSION}.tar.gz
+```
+
+You should reply to the `[VOTE]` thread with `+1`, `+0`, or `-1` and a one-line description of what you verified (for example, "verified signatures, checksums, and `verify_rc.sh` passed on macOS arm64 with system Go 1.25.5").