docs: comprehensive distributed execution guide + docs uplift (#24)

* docs: comprehensive docs uplift for recent features

New guide: Distributed IO — covers size-balanced reads, partition
pruning, Postgres hash-partitioned reads, DuckLake file manifest,
parallel writes, partition_by output, distributed insert_into. Includes
mermaid architecture diagrams and data flow charts.

Updated guides:
- data-io: add Excel IO, insert_into, database writes
- joins-and-reshape: add ASOF JOIN section, cross-source join tip
- cheatsheet: add ~15 missing functions (attach/detach, from_excel,
  to_excel, insert_into, partition_by, ASOF join, secrets, from_attached,
  distributed Postgres reads, distributed writes)

Updated mix.exs to include new guide in ExDoc extras.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: comprehensive distributed execution guide + docs uplift

Replace the thin distributed-queries.livemd and separate distributed-io.md
with a single comprehensive distributed.md guide covering the full story:

- Architecture (Coordinator → PipelineSplitter → Partitioner → Workers → Merger)
- Query decomposition with sequence diagram
- Pipeline splitting: worker-safe vs coordinator-only ops
- Aggregate rewrites (AVG→SUM/COUNT, STDDEV→Welford, COUNT DISTINCT→HLL)
- Streaming merger and lattice compatibility
- Data partitioning: size-balanced, Hive pruning, Postgres hash reads
- Source safety classification table
- Joins: broadcast (< 256MB) and shuffle (4-phase hash exchange)
- Distributed writes: parallel files, partition_by, insert_into
- Performance considerations and common pitfalls
- Fault tolerance summary
- Telemetry events table

Also updates data-io, joins-and-reshape, cheatsheet guides with Excel IO,
ASOF JOIN, insert_into, attach/from_attached, partition_by, secrets.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: fix 'connected by BEAM' → 'connected by the BEAM'

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cigrainger

guides/cheatsheet.cheatmd

@@ -13,6 +13,23 @@ Dux.from_csv("data.csv")
 Dux.from_csv("data.csv", delimiter: "\t", nullstr: "NA")
 Dux.from_parquet("data/**/*.parquet")
 Dux.from_ndjson("events.ndjson")
+Dux.from_excel("data.xlsx")
+Dux.from_excel("data.xlsx", sheet: "Sales", all_varchar: true)
+```
+
+### From databases
+```elixir
+Dux.attach(:pg, "host=... dbname=db", type: :postgres)
+Dux.from_attached(:pg, "public.orders")
+Dux.from_attached(:pg, "public.orders", partition_by: :id)
+Dux.detach(:pg)
+Dux.list_attached()
+```
+
+### Secrets
+```elixir
+Dux.create_secret(:s3, type: :s3, key_id: "...", secret: "...", region: "us-east-1")
+Dux.drop_secret(:s3)
 ```
 
 ### From SQL
@@ -132,6 +149,12 @@ Dux.join(flights, airports, on: [{:dest, :faa}])
 Dux.join(orders, users, on: [{:customer_id, :id}])
 ```
 
+### ASOF join (time series)
+```elixir
+Dux.asof_join(trades, quotes, on: :symbol, by: {:timestamp, :>=})
+Dux.asof_join(trades, quotes, on: :symbol, by: {:timestamp, :>=}, how: :left)
+```
+
 ### Concat rows (UNION ALL)
 ```elixir
 Dux.concat_rows([df1, df2, df3])
@@ -176,7 +199,15 @@ Dux.from_query("SELECT * FROM 'file.csv'")
 Dux.to_csv(df, "out.csv")
 Dux.to_parquet(df, "out.parquet")
 Dux.to_parquet(df, "out.parquet", compression: :zstd)
+Dux.to_parquet(df, "out/", partition_by: [:year, :month])
 Dux.to_ndjson(df, "out.ndjson")
+Dux.to_excel(df, "out.xlsx")
+```
+
+### Database writes
+```elixir
+Dux.insert_into(df, "my_table", create: true)
+Dux.insert_into(df, "pg.public.events")
 ```
 
 ## Materialization
@@ -194,22 +225,41 @@ Dux.sql_preview(df, pretty: true)  # → formatted SQL
 
 ## Distributed
 
+### Reads
 ```elixir
-# Discover or start workers
 workers = Dux.Remote.Worker.list()
 
-# Same verbs, automatically distributed
+# Size-balanced Parquet distribution
 Dux.from_parquet("s3://data/**/*.parquet")
 |> Dux.distribute(workers)
 |> Dux.filter(amount > 100)
 |> Dux.group_by(:region)
 |> Dux.summarise(total: sum(amount))
 |> Dux.to_rows()
 
-# Collect back to local %Dux{}
+# Hash-partitioned Postgres reads
+Dux.from_attached(:pg, "public.orders", partition_by: :id)
+|> Dux.distribute(workers)
+|> Dux.to_rows()
+```
+
+### Writes
+```elixir
+# Parallel file writes
+df |> Dux.distribute(workers) |> Dux.to_parquet("s3://out/")
+
+# Hive-partitioned output
+df |> Dux.distribute(workers) |> Dux.to_parquet("s3://out/", partition_by: :year)
+
+# Parallel database inserts
+df |> Dux.distribute(workers) |> Dux.insert_into("pg.public.events", create: true)
+
+# Collect back to local
 df |> Dux.distribute(workers) |> Dux.collect()
+```
 
-# FLAME: elastic cloud compute
+### FLAME: elastic cloud compute
+```elixir
 Dux.Flame.start_pool(backend: {FLAME.FlyBackend, ...}, max: 10)
 workers = Dux.Flame.spin_up(5)
 ```

guides/data-io.livemd

@@ -97,6 +97,60 @@ Dux.Datasets.penguins()
 "#{div(File.stat!(parquet_path).size, 1024)} KB"
 ```
 
+## Reading Excel
+
+DuckDB 1.5+ reads `.xlsx` files natively. Dux defaults to `ignore_errors: true`
+and `empty_as_varchar: true` for safe handling of messy spreadsheets:
+
+```elixir
+# xlsx_path = "sales.xlsx"
+# Dux.from_excel(xlsx_path) |> Dux.to_rows()
+#
+# # With options
+# Dux.from_excel("data.xlsx", sheet: "Q1 2024", range: "A1:F100")
+#
+# # For messy spreadsheets with mixed types
+# Dux.from_excel("messy.xlsx", all_varchar: true)
+```
+
+## Writing Excel
+
+```elixir
+# excel_out = Path.join(tmp_dir, "output.xlsx")
+# Dux.Datasets.penguins()
+# |> Dux.filter_with("species = 'Gentoo'")
+# |> Dux.to_excel(excel_out)
+```
+
+## Database Tables: `insert_into`
+
+Write pipeline results to a table — local DuckDB or an attached database:
+
+```elixir
+# Create a local table from a pipeline
+Dux.from_query("SELECT * FROM range(100) t(x)")
+|> Dux.insert_into("my_table", create: true)
+
+# Read it back
+Dux.from_query("SELECT * FROM my_table") |> Dux.n_rows()
+```
+
+```elixir
+# Cleanup
+conn = Dux.Connection.get_conn()
+Adbc.Connection.query(conn, "DROP TABLE IF EXISTS my_table")
+```
+
+> #### Attached databases {: .info}
+>
+> `insert_into` works with attached databases too:
+> ```elixir
+> Dux.attach(:pg, "host=... dbname=analytics", type: :postgres, read_only: false)
+> Dux.from_parquet("data.parquet")
+> |> Dux.insert_into("pg.public.events", create: true)
+> ```
+> See the [Distributed Execution](distributed.md) guide for parallel writes.
+
 ## The SQL Escape Hatch
 
 `from_query/1` lets you write raw DuckDB SQL for anything the verbs don't cover: