fdl-cli 0.13.0__tar.gz → 0.14.0__tar.gz

{fdl_cli-0.13.0 → fdl_cli-0.14.0}/.github/workflows/docs.yml

@@ -5,8 +5,10 @@ on:
     branches: [main]
     paths:
       - "docs/**"
-      - "zensical.toml"
-      - "CHANGELOG.md"
+      - "public/**"
+      - "blume.config.ts"
+      - "package.json"
+      - "package-lock.json"
       - ".github/workflows/docs.yml"
   workflow_dispatch:
 
@@ -24,11 +26,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: astral-sh/setup-uv@v7
-      - run: uv run zensical build
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v5
+        with:
+          node-version-file: .node-version
+          cache: npm
+      - run: npm ci
+      - run: npm run check
       - uses: actions/upload-pages-artifact@v4
         with:
-          path: site
+          path: dist
 
   deploy:
     needs: build

{fdl_cli-0.13.0 → fdl_cli-0.14.0}/.gitignore

@@ -18,3 +18,8 @@ site/
 
 # Environment
 .env
+
+# Docs (Blume)
+node_modules/
+dist/
+.blume/

fdl_cli-0.14.0/.node-version

@@ -0,0 +1 @@
+22

{fdl_cli-0.13.0 → fdl_cli-0.14.0}/CHANGELOG.md

@@ -1,6 +1,69 @@
 # CHANGELOG
 
 
+## v0.14.0 (2026-11-01)
+
+### Documentation
+
+- Add a Japanese translation of every page
+  ([`0d7bb97`](https://github.com/queria-io/fdl/commit/0d7bb9707d51b83fe029fef8f875a4007f4669ee))
+
+English stays the source. The Japanese pages live under docs/ja/ and are served at /ja/.
+
+- Bring in dataset.json and pushing over HTTP from the implementation
+  ([`0e7817b`](https://github.com/queria-io/fdl/commit/0e7817b9c120b7f683dcf00f23663480793e91f7))
+
+Port the specification and CLI text of fdl#23 into the new pages: dataset.json in each version, the
+  HTTP push requests, fdl login and commit --dataset.
+
+- Fix review findings in the spec and guides
+  ([`53e8cc4`](https://github.com/queria-io/fdl/commit/53e8cc4d20d4cfdc8dced8e529d899432aa1687f))
+
+Name the HTTP repository as the exception to where new data files go, say a host answers HEAD
+  requests, list withdrawal among the changes a version allows, add dataset.json to the second
+  commit example, pass DATA_PATH in the README reader, and say versions have one parent.
+
+- Rewrite the documentation with Blume and split the specification into pages
+  ([`8bfdb79`](https://github.com/queria-io/fdl/commit/8bfdb79039a63ee82f260d4e5b5689b701d47e48))
+
+Guide pages (getting started, concepts, how it works, guides) explain the format the way Git's
+  documentation does; docs/spec/ is the normative specification, with the data_path and DuckLake
+  format rules written in. GitHub Pages now builds the site with Blume.
+
+- **spec**: Settle the open questions
+  ([`b98a88f`](https://github.com/queria-io/fdl/commit/b98a88f4928a54deaa1c8298cd671c91d6b636a8))
+
+Add refs.json, ASCII-only ref names, one parent per version in 0.1, optional SSH signatures
+  (version.json.sig and signers in fdl.json), withdrawal, and leave retention defaults to hosts.
+  Remove the open questions page.
+
+### Features
+
+- Describe every version in dataset.json
+  ([`4608dec`](https://github.com/queria-io/fdl/commit/4608dec8631d12fafac2169ba5948f79988b202d))
+
+dataset.json is now part of a version, listed in version.json with its hash. fdl commit reads it,
+  refuses tables, columns and keys the format does not know, and fills in types, nulls, row counts
+  and comments from the catalog. --attach is gone.
+
+- Push to a repository over HTTP
+  ([`659399b`](https://github.com/queria-io/fdl/commit/659399b12f06e50aa229b8dee9d42d725f6aa427))
+
+A host can take pushes over plain HTTP: GET, HEAD and conditional PUT, a listing, and uploads in
+  parts for large files. The writer needs a token (fdl login, or FDL_TOKEN) instead of keys to the
+  storage.
+
+DuckDB cannot write data files over HTTP, so a working catalog of such a repository writes new files
+  to a folder beside it and reads the published ones where they are; commit makes both relative
+  again and push uploads the new ones. commit --attach keeps a file beside the version.
+
+- Read the description from dataset.yml too
+  ([`c04b6e8`](https://github.com/queria-io/fdl/commit/c04b6e891428b82749b231ab69d77f783d3b69ea))
+
+fdl commit looks for dataset.json, then dataset.yml, in the current directory. Licenses may be
+  written as bare SPDX identifiers.
+
+
 ## v0.13.0 (2026-11-01)
 
 ### Features

{fdl_cli-0.13.0 → fdl_cli-0.14.0}/CLAUDE.md

@@ -6,9 +6,20 @@
 uv sync
 uv run fdl --help
 uv run pytest
-uv run zensical serve
 ```
 
+Docs (Blume, served at https://fdl.flo8s.com):
+
+```bash
+npm ci
+npm run dev
+npm run check   # blume build --strict && blume validate --strict
+```
+
+The pages under `docs/spec/` are the specification. Change the spec first, then the code.
+
+English is the source; `docs/ja/` mirrors every page in Japanese. Change both in the same PR (plain です・ます, 「バージョン」 not 「版」).
+
 ## Code style
 
 - Python 3.10+ — `X | Y` unions are fine; nothing newer (no `typing.Self`, `except*`, `datetime.UTC`)

{fdl_cli-0.13.0 → fdl_cli-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fdl-cli
-Version: 0.13.0
+Version: 0.14.0
 Summary: Versions of a DuckLake catalog on object storage, kept the way Git keeps commits
 Project-URL: Homepage, https://fdl.flo8s.com/
 Project-URL: Documentation, https://fdl.flo8s.com/
@@ -11,6 +11,7 @@ License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: duckdb<2.0,>=1.5.2
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: typer>=0.15
 Provides-Extra: s3
 Requires-Dist: boto3>=1.36; extra == 's3'
@@ -37,7 +38,7 @@ FDL is a storage layout and a tool for it. Each version is a frozen catalog with
   data/main/towns/ducklake-….parquet
 ```
 
-The format is in [docs/spec.md](docs/spec.md).
+The documentation and the specification are at [fdl.flo8s.com](https://fdl.flo8s.com).
 
 ## Quick start
 
@@ -76,7 +77,9 @@ fdl url s3://my-bucket/towns/
 ```
 
 ```sql
-ATTACH 'ducklake:s3://my-bucket/towns/versions/019a3c4e-…/ducklake.duckdb' AS towns (READ_ONLY);
+ATTACH 'ducklake:s3://my-bucket/towns/versions/019a3c4e-…/ducklake.duckdb' AS towns (
+  DATA_PATH 's3://my-bucket/towns/data/', OVERRIDE_DATA_PATH true, READ_ONLY
+);
 ```
 
 Credentials and the endpoint come from boto3's usual places (`AWS_*` environment variables, `AWS_ENDPOINT_URL` for R2 and other S3-compatible stores). A folder works as a repository too: pass its path instead of an `s3://` URL.

{fdl_cli-0.13.0 → fdl_cli-0.14.0}/README.md

@@ -19,7 +19,7 @@ FDL is a storage layout and a tool for it. Each version is a frozen catalog with
   data/main/towns/ducklake-….parquet
 ```
 
-The format is in [docs/spec.md](docs/spec.md).
+The documentation and the specification are at [fdl.flo8s.com](https://fdl.flo8s.com).
 
 ## Quick start
 
@@ -58,7 +58,9 @@ fdl url s3://my-bucket/towns/
 ```
 
 ```sql
-ATTACH 'ducklake:s3://my-bucket/towns/versions/019a3c4e-…/ducklake.duckdb' AS towns (READ_ONLY);
+ATTACH 'ducklake:s3://my-bucket/towns/versions/019a3c4e-…/ducklake.duckdb' AS towns (
+  DATA_PATH 's3://my-bucket/towns/data/', OVERRIDE_DATA_PATH true, READ_ONLY
+);
 ```
 
 Credentials and the endpoint come from boto3's usual places (`AWS_*` environment variables, `AWS_ENDPOINT_URL` for R2 and other S3-compatible stores). A folder works as a repository too: pass its path instead of an `s3://` URL.

fdl_cli-0.14.0/blume.config.ts

@@ -0,0 +1,28 @@
+import { defineConfig } from "blume";
+
+export default defineConfig({
+  title: "FDL",
+  description: "Versions of a DuckLake catalog on object storage, kept the way Git keeps commits",
+  theme: {
+    accent: "#673ab7",
+  },
+  deployment: {
+    site: "https://fdl.flo8s.com",
+  },
+  content: {
+    root: "docs",
+  },
+  i18n: {
+    defaultLocale: "en",
+    locales: [
+      { code: "en", label: "English" },
+      { code: "ja", label: "日本語" },
+    ],
+  },
+  seo: {
+    og: {
+      fonts: ["Noto Sans JP"],
+    },
+  },
+  redirects: [{ from: "/cli", to: "/reference/cli" }],
+});

fdl_cli-0.14.0/docs/concepts/meta.ts

@@ -0,0 +1,7 @@
+import { defineMeta } from "blume";
+
+export default defineMeta({
+  title: "Concepts",
+  order: 2,
+  pages: ["repositories", "versions-and-refs", "working-catalogs"],
+});

fdl_cli-0.14.0/docs/concepts/repositories.md

@@ -0,0 +1,47 @@
+---
+title: Repositories
+description: What a repository is, what it needs from the store it lives in, and what it leaves to the host.
+---
+
+A repository is everything under one prefix of a store: `s3://bucket/lake/` on S3, R2 or another S3-compatible store, or a folder on disk. It is what a bare Git repository is on a server. There is no index file and no process that owns it. Every reader and writer works on the same files, under the rules in the [specification](/spec).
+
+## What a store has to do
+
+| Operation | Used by | For |
+| --- | --- | --- |
+| read an object | readers and writers | refs, `version.json`, catalogs, data files |
+| write an object | writers | data files, catalogs, `version.json` |
+| write on condition | writers | refs: create only if absent, replace only if unchanged |
+| list a prefix | maintenance | finding data files that no version names |
+| delete | maintenance | catalogs of versions past retention, and unused data files |
+
+Conditional writes are what make two writers safe. A ref is created with `If-None-Match: *` and moved with `If-Match: <the ETag that was read>`. If someone else moved it in between, the store refuses the write and nothing changes. S3 and R2 support this. The folder store checks the condition without a lock, so it suits one writer at a time (see [Stores](/guides/stores)). A store without conditional writes can still be read from, but must not be pushed to: the last writer would silently replace someone else's version.
+
+Readers only read. A static HTTP server in front of the repository is enough for them.
+
+## What is in a repository
+
+```
+<root>/
+  fdl.json                 settings: format version, ID, where data files are
+  HEAD                     the default branch
+  refs/heads/<name>        branches
+  refs/tags/<name>         tags
+  versions/<ID>/           one folder per version
+  data/                    Parquet files, shared by all versions
+  sources/<sha256>         the files a version was built from (optional)
+```
+
+The repository holds no catalog outside a version folder, and never a working catalog. Either would hand readers a state that was never published.
+
+`fdl.json` carries an `id`, a UUID written once by `fdl init`. Copies of the repository on other hosts keep the same `id`, so a tool can tell that two URLs hold the same repository. A service that hosts repositories may write its own ID for the dataset there.
+
+## What FDL leaves to the host
+
+FDL describes files. It does not say who may read them, who may move `main`, or what a URL looks like. Those belong to whoever hosts the repository:
+
+- access control. Everything in one repository is readable by the same people. To publish part of a dataset, make a second repository (see [Public and private data](/guides/public-and-private))
+- approval. A host may keep writers from moving refs and move them itself after a review (see [Building a host](/guides/building-a-host))
+- authentication, URL shapes and how long versions are kept
+
+Nothing in the format names a host or a service. A repository can move from one host to another by copying its files.

fdl_cli-0.14.0/docs/concepts/versions-and-refs.md

@@ -0,0 +1,86 @@
+---
+title: Versions and refs
+description: A version is a frozen catalog with a record; a ref is a name that points at one. How they relate to DuckLake snapshots and to Git commits.
+---
+
+## Versions
+
+A version is one frozen DuckLake catalog and a record of how it came to be. It lives in its own folder and is never changed once written.
+
+```
+versions/019a3c4e-7b21-7f3a-9c55-2f0d8e1a4b6c/
+  version.json         the record: parents, author, message, checksums
+  dataset.json         what it holds: tables, columns, license
+  ducklake.duckdb      the frozen catalog
+```
+
+The record says:
+
+- `id`: the version ID, a UUIDv7. IDs sort by creation time, and two writers never make the same one
+- `seq`: the number shown to people, the parent's `seq` plus one
+- `parents`: the version it was built on. Empty for the first
+- `author`, `message` and `created_at`
+- `catalog`: the size and sha256 of the catalog file, so a reader can check what it fetched
+- `ducklake`: the DuckLake format of the catalog and the snapshot it was frozen at
+
+The ID is not a hash of the content, as a Git commit's is. The same catalog can be written as different bytes by two DuckDB releases, so a content hash would not be stable. The sha256 in `catalog` checks the content instead.
+
+The full list of fields is in [Versions](/spec/versions) in the specification.
+
+## Snapshots and versions
+
+DuckLake makes a snapshot on every write: each `INSERT`, `CREATE TABLE` or `ALTER` in its own transaction. A day of work can make hundreds. A version is made when you decide the work is ready, and it takes the last of those snapshots.
+
+A snapshot is to a version what a commit on a work branch is to the squashed commit that lands on `main`. The snapshots stay inside the catalog, with their `commit_message` and `commit_extra_info`, so the detail is not lost. `version.json` records the range of snapshots the version adds after its parent, but does not copy them.
+
+## Refs
+
+A ref is a file that holds a version ID and a newline. It is how a reader finds a version without knowing its ID.
+
+```
+refs/heads/main          019a3c4e-7b21-7f3a-9c55-2f0d8e1a4b6c
+refs/tags/2025-final     019a2f10-0c4d-7e88-a1b2-55c0d9e3f7aa
+HEAD                     ref: refs/heads/main
+```
+
+| Kind | Path | Moves |
+| --- | --- | --- |
+| branch | `refs/heads/<name>` | yes, forward |
+| tag | `refs/tags/<name>` | never |
+| request | `refs/requests/<number>` | as the host decides |
+| HEAD | `HEAD` | rarely |
+
+`main` is the branch readers get unless they ask for another. `HEAD` names it, as in Git. A tag pins a version that readers can rely on, such as the final figures of a year. `refs/requests/` is for hosts: a version waiting for approval can be held there without being on `main`.
+
+Refs are the only files in a repository that change. Everything else is written once.
+
+## Moving a branch
+
+A branch moves forward only. A new version can become `main` when its `parents` include the version `main` holds now. This is a fast-forward in Git's terms.
+
+```
+main → A
+           Alice checks out A, commits B (parent A), pushes: main → B
+           Bob checked out A too, commits C (parent A), pushes: refused
+```
+
+Bob's push is refused because C is not built on B. If it were accepted, B would vanish from the history of `main` with no one deciding that. Bob checks out B and makes his change again.
+
+FDL does not merge rows. Merging two DuckLake catalogs would mean deciding which row wins when both sides changed it, and DuckLake gives tables no identity across catalogs that would make that safe. Redoing the change on the new version is usually a matter of running the same SQL again.
+
+Moving a branch back, to undo a version, is allowed only when asked for explicitly. The version that was undone stays in the repository and in the history.
+
+## History
+
+`fdl log` follows the first parent from the version a ref holds back to the first one:
+
+```
+   3  019a4b…  2026-11-01T09:00:00Z  alice
+      Correct the 2026 figures
+   2  019a3c…  2026-10-15T09:00:00Z  bob
+      Add 2026
+   1  019a2f…  2026-10-01T09:00:00Z  alice
+      First towns
+```
+
+Versions that were taken out of retention stay in the history. Their record is kept, only their catalog is gone. See [Retention](/internals/inside-a-repository#taking-versions-out-of-retention).

fdl_cli-0.14.0/docs/concepts/working-catalogs.md

@@ -0,0 +1,48 @@
+---
+title: Working catalogs
+description: "Where writing happens: a DuckLake catalog in SQLite, checked out from a version and frozen into the next one."
+---
+
+A working catalog is a DuckLake catalog in a SQLite file, on the writer's own disk or in a container. It is the only place anyone writes to. It is to FDL what a working tree is to Git: made from a version, changed freely, and turned into the next version when the change is ready.
+
+## The cycle
+
+| Step | Command | What happens |
+| --- | --- | --- |
+| check out | `fdl checkout` | Copy the catalog of the branch's version into SQLite, and remember that version |
+| write | any DuckDB client | DuckLake writes Parquet into the repository and bookkeeping into SQLite |
+| commit | `fdl commit` | Freeze the last snapshot into a new version, upload it, move the branch |
+
+Checking out copies DuckLake's bookkeeping tables from the frozen DuckDB file into SQLite as they are. Freezing does the reverse. Neither rewrites a Parquet file, so both are fast even for a large dataset: the catalog is small and the data stays where it is.
+
+## Why SQLite
+
+A working catalog has to be written by DuckDB and kept between sessions. SQLite does both without a database server, works the same on a laptop and in a container, and copies in and out of DuckDB's format without loss.
+
+There is one kind of working catalog. A host that writes on behalf of its users (a scheduled import, a web form) checks out, writes and commits the same way a person does on a laptop. When two of them commit at once, the conditional write on the ref settles it: one wins, and the other checks out again.
+
+## Attaching
+
+`fdl checkout` prints the statement to attach the working catalog with:
+
+```sql
+ATTACH 'ducklake:work/lake.sqlite' AS lake (
+  DATA_PATH 's3://my-bucket/towns/data/', OVERRIDE_DATA_PATH true,
+  META_TYPE 'sqlite', DATA_INLINING_ROW_LIMIT 0,
+  META_JOURNAL_MODE 'WAL', BUSY_TIMEOUT 5000
+);
+```
+
+- `DATA_PATH` is the repository's data folder, so new Parquet files land where readers will look for them. For a repository over HTTP it is a folder beside the working catalog instead, and `fdl commit` uploads the new files (see [Pushing over HTTP](/spec/http#writing-to-it))
+- `DATA_INLINING_ROW_LIMIT 0` keeps every row out of the catalog. A version must not carry inlined rows, and `fdl commit` refuses a working catalog that holds some
+- `META_TYPE 'sqlite'` has to be stated. Left to guess from the file, DuckDB passes an option to SQLite that SQLite rejects
+
+## Data files written before a commit
+
+DuckLake writes Parquet as you go, so data files reach the repository before any version names them. Readers never see them: a reader only opens catalogs of versions, and no version names those files yet.
+
+A file that stays unnamed for longer than the grace period (7 days by default) may be deleted by maintenance. Commit within that time. If a commit is refused because a file it names is missing, rebuild the table in the working catalog and commit again.
+
+## Snapshots in the working catalog
+
+Do not run `ducklake_expire_snapshots` or `ducklake_cleanup_old_files` on a working catalog. They only see the working catalog, not the repository, and would delete files that other versions still name. Removing old versions and files is done on the repository as a whole (see [Retention](/internals/inside-a-repository#taking-versions-out-of-retention)).

fdl_cli-0.14.0/docs/getting-started.md

@@ -0,0 +1,139 @@
+---
+title: Getting started
+description: Make a repository, write a first version with DuckDB, and read it back.
+---
+
+This page makes a repository in a folder, writes a table into it and reads the result as a reader would. The same commands work on S3 and R2: pass `s3://bucket/prefix/` instead of a folder.
+
+## Install
+
+```bash
+pip install 'fdl-cli[s3]'
+```
+
+The package installs the `fdl` command and the `fdl` Python package. Python 3.10 or later is needed. Leave out `[s3]` if you only use folders.
+
+## Make a repository
+
+```bash
+fdl init ./towns/
+```
+
+`init` writes two files and nothing else:
+
+```
+towns/
+  fdl.json      {"fdl": "0.1", "id": "5f0c…", "data_dir": "data/"}
+  HEAD          ref: refs/heads/main
+```
+
+`HEAD` names the default branch, `main`. The branch itself does not exist yet: there is no version for it to point at.
+
+## Check out a working catalog
+
+You never write to the repository directly. You write to a working catalog, a DuckLake catalog in a SQLite file on your own disk, and turn it into a version when you are done.
+
+```bash
+fdl checkout ./towns/ work/lake.sqlite
+```
+
+Before the first version, `checkout` makes an empty catalog. Later it copies the catalog of the version `main` holds. It prints the statement to attach the working catalog with:
+
+```sql
+ATTACH 'ducklake:work/lake.sqlite' AS lake (
+  DATA_PATH '/abs/path/towns/data/', OVERRIDE_DATA_PATH true,
+  META_TYPE 'sqlite', DATA_INLINING_ROW_LIMIT 0,
+  META_JOURNAL_MODE 'WAL', BUSY_TIMEOUT 5000
+);
+```
+
+Beside the working catalog, `work/lake.sqlite.fdl.json` remembers the repository, the branch and the version the checkout was made from.
+
+## Write
+
+Use any DuckDB client. The Parquet files go straight into the repository's `data/` folder.
+
+```sql
+CREATE TABLE lake.main.towns AS
+SELECT * FROM 'towns.csv';
+```
+
+`DATA_INLINING_ROW_LIMIT 0` makes DuckLake write every row to Parquet. Left at its default, DuckLake keeps small tables inside the catalog, and a version has to carry its rows in data files that a reader can fetch.
+
+## Describe
+
+Every version carries a `dataset.json` that says what it holds. Write one next to where you run `fdl commit`:
+
+```json dataset.json
+{
+  "name": "towns",
+  "title": "Towns",
+  "tables": [{ "schema": "main", "name": "towns", "title": "Towns and their codes" }]
+}
+```
+
+Only `name` and `title` are required. `fdl commit` checks the file against the catalog and fills in each table's row count and each column's type.
+
+## Commit
+
+```bash
+fdl commit work/lake.sqlite -m "First towns" --author alice
+```
+
+`commit` freezes the working catalog into a version, uploads it and moves `main` to it. It prints `refs/heads/main -> 019a3c4e-… (version 1)`. The repository now holds:
+
+```
+towns/
+  fdl.json
+  HEAD
+  refs/heads/main                       019a3c4e-…
+  versions/019a3c4e-…/
+    ducklake.duckdb
+    dataset.json
+    version.json
+  data/main/towns/ducklake-….parquet
+```
+
+```bash
+fdl log ./towns/
+```
+
+```
+   1  019a3c4e-…  2026-11-01T09:00:00Z  alice
+      First towns
+```
+
+## Read
+
+```bash
+fdl url ./towns/
+```
+
+prints the catalog of the version `main` holds. Attach it read-only, and tell DuckDB where the data files are:
+
+```sql
+ATTACH 'ducklake:towns/versions/019a3c4e-…/ducklake.duckdb' AS towns (
+  DATA_PATH 'towns/data/', OVERRIDE_DATA_PATH true, READ_ONLY
+);
+SELECT count(*) FROM towns.main.towns;
+```
+
+A version's catalog never changes, so a reader may cache it forever. Only `HEAD` and the files under `refs/` change.
+
+## Make a second version
+
+```bash
+fdl checkout ./towns/ work/lake.sqlite
+```
+
+```sql
+INSERT INTO lake.main.towns SELECT * FROM 'towns-2026.csv';
+```
+
+```bash
+fdl commit work/lake.sqlite -m "Add 2026" --author alice
+```
+
+The new version lists the first as its parent. Both catalogs name the first Parquet file; only the second names the new one.
+
+If someone else committed in between, the commit is refused, because the new version would not be built on what `main` holds now. Check out again and redo the change. [Versions and refs](/concepts/versions-and-refs) explains why.

fdl_cli-0.14.0/docs/guides/building-a-host.md

@@ -0,0 +1,53 @@
+---
+title: Building a host
+description: Using the fdl Python package in a service that stores repositories for others, approves changes and moves refs itself.
+---
+
+A host is a service that keeps repositories for other people: it decides who can read and write them, and often reviews a change before readers see it. The `fdl` package is written for this. A host calls it the way a code hosting service calls Git. Nothing in the package knows about any host.
+
+## Writers that cannot move refs
+
+A host that reviews changes keeps writers from writing refs. The writer uploads a version and stops:
+
+```python
+from fdl import repo
+from fdl.stores import open_store
+
+store = open_store("s3://lake/towns/")
+version = repo.commit(working, out, parent=base, data_path=repo.data_url(store),
+                      author={"name": "alice"}, message="Add 2026")
+repo.push(store, out / version.id, version, move_ref=False)
+```
+
+The version is in the repository but no ref points at it, so readers do not see it. The host can hold it under `refs/requests/<number>` while it waits for approval. A request ref is an ordinary ref: it holds a version ID and a newline.
+
+## Approving
+
+On approval, the host moves `main` itself, on the same condition a writer would:
+
+```python
+from fdl import refs
+
+current = refs.read(store, "refs/heads/main")
+refs.write(store, "refs/heads/main", version.id, expected=current)
+```
+
+The host checks that the version is built on what `main` holds now (`repo.is_ancestor`). If `main` moved since the request was made, the request is out of date and the writer builds again.
+
+## Writing on behalf of users
+
+A scheduled import or a form in a web app writes the same way a person does: check out into a SQLite file in a container, write with DuckDB, commit. Two jobs that commit at once are settled by the conditional write on the ref. The loser checks out again and reruns its SQL.
+
+## Keeping the host out of the format
+
+What a host adds goes outside the fields FDL defines:
+
+- extra files in a version folder (a preview), which readers ignore
+- `extensions` in `version.json` and `dataset.json`, keyed by the host's name
+- its own ID for the dataset in `fdl.json`'s `id`, written at `init` and never changed
+
+Access rules, approvals and billing stay in the host's own database. A repository copied off the host still reads correctly, with nothing in it that only the host understands.
+
+## Retention
+
+`repo.prune` takes versions out of retention and `repo.expire` takes out one. Deleting data files that no live version names is left to the host, which can list the whole repository and read every live catalog. See [Data files](/spec/data-files) for when a file may be deleted.

fdl_cli-0.14.0/docs/guides/meta.ts

@@ -0,0 +1,7 @@
+import { defineMeta } from "blume";
+
+export default defineMeta({
+  title: "Guides",
+  order: 4,
+  pages: ["stores", "serving-over-http", "mirrors", "public-and-private", "building-a-host"],
+});