From fa1a9843de5a70a0c2d0c1f5aa18122b97b1da2c Mon Sep 17 00:00:00 2001
From: Haitao Pan <manbuzhe2009@qq.com>
Date: Tue, 5 May 2026 11:13:08 +0800
Subject: [PATCH] Document xworkmate artifacts plugin

---
 README.md | 42 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 37 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 3f2d866..12ebc95 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,14 @@
 
 OpenClaw Gateway plugin that exports structured workspace artifact manifests for XWorkmate.
 
+## Why
+
+XWorkmate talks to OpenClaw through `xworkmate-bridge` using the existing
+`/gateway/openclaw` task contract. The bridge sends `chat.send`, waits for
+`agent.wait`, then asks this plugin for a structured artifact manifest. The APP
+can then sync generated files into its local thread workspace without changing
+the UI or adding provider-specific routes.
+
 It registers one Gateway method:
 
 ```text
@@ -10,23 +18,31 @@ xworkmate.artifacts.export
 
 The method scans the resolved OpenClaw workspace after a run finishes and returns safe, relative artifact entries that XWorkmate Bridge can normalize into the APP `artifacts[]` contract.
 
-## Install locally
+## Install
 
-Link this directory into OpenClaw:
+Install from npm:
 
 ```bash
-openclaw plugins install --link /Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-artifacts
+npm install -g xworkmate-artifacts
 openclaw plugins enable xworkmate-artifacts
 ```
 
-Equivalent config shape:
+Or install from a Git checkout for development:
+
+```bash
+git clone https://github.com/x-evor/xworkmate-artifacts.git
+openclaw plugins install --link ./xworkmate-artifacts
+openclaw plugins enable xworkmate-artifacts
+```
+
+Equivalent config shape for a linked checkout:
 
 ```json
 {
   "plugins": {
     "load": {
       "paths": [
-        "/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-artifacts"
+        "/path/to/xworkmate-artifacts"
       ]
     },
     "entries": {
@@ -74,3 +90,19 @@ Response payload:
 ```
 
 Files at or below `maxInlineBytes` also include `encoding: "base64"` and `content`.
+
+## Limits
+
+- Only files inside the resolved OpenClaw workspace are exported.
+- `.git`, `.openclaw`, `.pi`, build outputs, and dependency folders are skipped.
+- Symlinks are skipped to avoid workspace escape.
+- Files larger than `maxInlineBytes` are listed with metadata and a warning, but are not inlined.
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm typecheck
+pnpm pack:check
+```