From cc752520474aec85bdf60f0545bd21990dbda68a Mon Sep 17 00:00:00 2001
From: BillyOutlast <172061051+BillyOutlast@users.noreply.github.com>
Date: Sun, 25 Oct 2026 16:56:09 -0900
Subject: [PATCH] v0.3.0: remote library docs, API reference, version bump

---
 README.md              |  7 +++++++
 assetmgr/__init__.py   |  2 +-
 docs/API.md            |  6 +++++-
 docs/REMOTE_LIBRARY.md | 47 ++++++++++++++++++++++++++++++++++++++++++
 pyproject.toml         |  2 +-
 5 files changed, 61 insertions(+), 3 deletions(-)
 create mode 100644 docs/REMOTE_LIBRARY.md

diff --git a/README.md b/README.md
index e468de8..d8847cb 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,13 @@ and a **Python automation API**.
 | ![Actions console](docs/screenshots/actions-console.png) | ![Project browser](docs/screenshots/project-browser.png) |
 | Run tab, discovery + one-click actions | Scan of the demo Godot project: import badges, params, live thumbnail |
 
+## Remote library (self-hosted)
+
+Publish once, download on demand: the `library` compose service hosts the
+team catalog (content-addressed blobs + token-auth API), and the
+`godot-plugin/` editor dock browses and pulls assets straight into
+`res://` — see [docs/REMOTE_LIBRARY.md](docs/REMOTE_LIBRARY.md).
+
 ## Quick start (Python host)
 
 ```bash
diff --git a/assetmgr/__init__.py b/assetmgr/__init__.py
index 8431b38..8cf32f1 100644
--- a/assetmgr/__init__.py
+++ b/assetmgr/__init__.py
@@ -1,3 +1,3 @@
 """Asset-Manager core package."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
diff --git a/docs/API.md b/docs/API.md
index 2a57f97..ade83a7 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -71,4 +71,8 @@ curl -X POST localhost:8080/api/thumbnail \
 `assetmgr actions [--root] [--scope file]` · `validate` · `info` ·
 `project-init DIR --name N [--force]` · `run <action-id> [--path P]` ·
 `status [--path P]` (offline `git status`) · `project-scan <root>` (Godot
-asset inventory) · `thumbnail SRC [--out PNG]` (exit 3 = no engine).
+asset inventory) · `thumbnail SRC [--out PNG]` (exit 3 = no engine) ·
+`library-init DIR` · `library-push FILE --server URL --token T [--name N]
+[--kind K] [--importer I] [--params JSON] [--tags a,b]` ·
+`library-pull ID --out PATH --server URL --token T`
+(server/token also via `ASSETMGR_LIBRARY_URL` / `ASSETMGR_LIBRARY_TOKEN`).
diff --git a/docs/REMOTE_LIBRARY.md b/docs/REMOTE_LIBRARY.md
new file mode 100644
index 0000000..b55d9c1
--- /dev/null
+++ b/docs/REMOTE_LIBRARY.md
@@ -0,0 +1,47 @@
+# Remote asset library (self-hosted)
+
+One team library, many thin Godot checkouts. Artists publish finished
+assets once; developers browse the catalog from inside the editor and
+download only what they need — no terabyte clones, no vendor cloud.
+
+## Run it
+
+```bash
+cp .env.example .env        # then set a real ASSETMGR_LIBRARY_TOKEN
+docker compose up -d --build library
+curl localhost:8081/health # -> {"ok": true}
+```
+
+Data lives in the `library-data` volume (`store/` blobs + `library.db`).
+The API is token-authenticated (`Authorization: Bearer <token>`):
+
+- `GET /api/v1/assets?q=&tag=&kind=` — search the catalog
+- `POST /api/v1/assets?name=&kind=&importer=&params={}&tags=` (raw body)
+  — publish; replies `{"id", "blob_sha256"}` (dedupe is by content hash)
+- `GET /api/v1/assets/<id>/blob` — download bytes
+
+The same operations exist offline-first on the CLI:
+`assetmgr library-init|library-push|library-pull` (see `docs/API.md`).
+Uploads are capped at 2 GiB (`MAX_UPLOAD_BYTES`); no chunked upload yet.
+
+## Connect Godot
+
+1. Copy `godot-plugin/addons/asset_library/` into your project's `addons/`.
+2. Project → Project Settings → Plugins → enable **Asset Library**.
+3. Open the dock (left), enter server URL + token, Search, select, Download.
+   Files land in `res://<name>` and the editor filesystem rescans, so
+   `.import` sidecars generate on the spot.
+
+Publish the other way with the `godot::publish-to-library` action
+(importer + params travel in the upload), or plain
+`assetmgr library-push`.
+
+## Security notes (read before exposing this)
+
+- Token auth only, **no TLS, no users, no rate limiting**. Safe on a LAN /
+  VPN or behind a reverse proxy that adds TLS — do not put 8081 directly
+  on the internet.
+- Tokens live in `.env` (git-ignored; see `.env.example`). Rotate by
+  changing the value and recreating the container.
+- The server trusts its operator: anyone with the token can read and
+  write every asset.
diff --git a/pyproject.toml b/pyproject.toml
index 393ec39..c0da3d7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "asset-manager"
-version = "0.2.0"
+version = "0.3.0"
 description = "OSS asset manager: action-plugin host, git-first version control, Python automation API"
 readme = "README.md"
 requires-python = ">=3.10"