@elaraai/e3-cloud-codex-plugin 1.0.91 → 1.0.93

package/.build/hooks/codex-tools.js

@@ -1,11 +1,11 @@
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.91_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/codex-hook.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.93_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/codex-hook.js
 import { readFile as readFile2 } from "node:fs/promises";
 import { existsSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
 import { join, resolve as resolve3 } from "node:path";
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.91_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/codex-tools.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.93_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/codex-tools.js
 import { resolve } from "node:path";
 function patchFiles(command, cwd) {
   const files = [];
@@ -43,7 +43,7 @@ function shellReadPaths(command, cwd) {
   return [...paths];
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.91_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/bash-writes.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.93_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/bash-writes.js
 import { resolve as resolve2 } from "node:path";
 function isRealPath(token) {
   if (token === "" || token.startsWith("&"))
@@ -92,7 +92,7 @@ function writtenPaths(command, cwd) {
   return [...found];
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.91_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.93_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
 import { readFile } from "node:fs/promises";
 var SEARCH_TOOLS = ["mcp__plugin_east_east__search_east_examples", "mcp__plugin_east_east__get_east_example", "mcp__east__search_east_examples", "mcp__east__get_east_example"];
 async function searchedInTranscript(transcriptPath, tools = SEARCH_TOOLS) {
@@ -105,7 +105,7 @@ async function searchedInTranscript(transcriptPath, tools = SEARCH_TOOLS) {
   return tools.some((tool) => raw.includes(`"name":"${tool}"`) || raw.includes(`"name": "${tool}"`));
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.91_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.93_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
 var EAST_GUIDANCE = {
   searchTool: "mcp__plugin_east_east__search_east_examples",
   getTool: "mcp__plugin_east_east__get_east_example",
@@ -147,7 +147,7 @@ var GATE_TEXT = gateText(EAST_GUIDANCE);
 var READ_TEXT = readText(EAST_GUIDANCE);
 var isExampleCorpusRead = corpusReadFor(EAST_GUIDANCE.scope);
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.91_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/codex-hook.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.93_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/codex-hook.js
 function codexToolCall(event) {
   const cwd = event.cwd || process.cwd();
   const input = event.tool_input ?? {};
@@ -199,7 +199,7 @@ async function codexSearchGate(event, options, call = codexToolCall(event)) {
   return context.length > 0 ? { decision: "context", text: context.join("\n\n") } : null;
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.91_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/host.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.93_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/host.js
 import { existsSync as existsSync2 } from "node:fs";
 import { fileURLToPath } from "node:url";
 var isCodex = existsSync2(fileURLToPath(new URL("../../.codex-plugin/plugin.json", import.meta.url)));
@@ -207,7 +207,7 @@ function hostText(text) {
   return isCodex ? text.replaceAll("mcp__plugin_east_east__", "").replaceAll("/east:", "$east-codex-plugin:").replaceAll("Claude Code", "Codex") : text;
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.91_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/hook-io.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.93_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/hook-io.js
 async function readHookInput() {
   let input = "";
   for await (const chunk of process.stdin) {
@@ -235,7 +235,7 @@ function writeHookDecision(hookEventName, decision, reason) {
   process.stdout.write(JSON.stringify(output));
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.91_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.93_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
 function writeSearchHookReply(hookEventName, reply) {
   if (reply.decision === "deny")
     writeHookDecision(hookEventName, "deny", reply.text);
@@ -256,9 +256,9 @@ var E3_CLOUD_GUIDANCE = {
   corpus: E3_CLOUD_CORPUS,
   scope: "@elaraai"
 };
-var E3_CLOUD_CODE = /@elaraai\/e3-cloud-(?:ui|client)\b/;
-var PACKAGE_PATH = /[/\\]node_modules[/\\]@elaraai[/\\]e3-cloud-(?:ui|cli|client)(?:[/\\]|$)/;
-var PACKAGE_PATTERN = /(?:^|[/\\])node_modules[/\\]@elaraai[/\\]e3-cloud-(?:ui|cli|client)(?:[/\\]|$)/;
+var E3_CLOUD_CODE = /@elaraai\/e3-cloud-(?:ui|files|client)\b/;
+var PACKAGE_PATH = /[/\\]node_modules[/\\]@elaraai[/\\]e3-cloud-(?:ui|files|cli|client)(?:[/\\]|$)/;
+var PACKAGE_PATTERN = /(?:^|[/\\])node_modules[/\\]@elaraai[/\\]e3-cloud-(?:ui|files|cli|client)(?:[/\\]|$)/;
 function isE3CloudCorpusRead(tool, input) {
   const text = (key) => typeof input[key] === "string" ? input[key] : "";
   return tool === "Read" ? PACKAGE_PATH.test(text("file_path")) : PACKAGE_PATH.test(text("path")) || PACKAGE_PATTERN.test(text("pattern"));
@@ -280,7 +280,7 @@ var E3_CLOUD_CODEX_SEARCH_GATE = {
   gateText: E3_CLOUD_SEARCH_GATE.gateText,
   readText: E3_CLOUD_READ_REMINDER.readText,
   isCorpusRead: isE3CloudCorpusRead,
-  shellSweep: /node_modules\/@elaraai\/e3-cloud-(?:ui|cli|client)\b/,
+  shellSweep: /node_modules\/@elaraai\/e3-cloud-(?:ui|files|cli|client)\b/,
   corpusCode: E3_CLOUD_CODE,
   markerPrefix: "e3-cloud-codex-search-",
   requireSearchEnv: "E3_CLOUD_REQUIRE_SEARCH"

package/.build/mcp/server.js

@@ -21491,7 +21491,7 @@ var StdioServerTransport = class {
   }
 };
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.91_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.93_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
 import { readFile } from "node:fs/promises";
 
 // ../../node_modules/.pnpm/minisearch@7.2.0/node_modules/minisearch/dist/es/index.js
@@ -23304,7 +23304,7 @@ var objectToNumericMapAsync = async (object3) => {
 var wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var SPACE_OR_PUNCTUATION = /[\n\r\p{Z}\p{P}]+/u;
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.91_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.93_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
 var EAST_GUIDANCE = {
   searchTool: "mcp__plugin_east_east__search_east_examples",
   getTool: "mcp__plugin_east_east__get_east_example",
@@ -23346,7 +23346,7 @@ var GATE_TEXT = gateText(EAST_GUIDANCE);
 var READ_TEXT = readText(EAST_GUIDANCE);
 var isExampleCorpusRead = corpusReadFor(EAST_GUIDANCE.scope);
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.91_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.93_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
 var MIN_SCORE = 5;
 async function loadIndexes(indexPaths) {
   const entries = [];
@@ -23471,7 +23471,7 @@ function getEntry(index, id) {
   return stored === void 0 ? null : stored;
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.91_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/mcp/example-tools.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.93_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/mcp/example-tools.js
 var EAST_PACKAGES = ["east", "east-node-std", "east-node-io", "east-py-datascience", "east-ui", "e3-ui", "e3", "e3-ui-cli", "e3-create"];
 function isLoaded(index) {
   return typeof index.then === "function";
@@ -23544,7 +23544,7 @@ function registerExampleTools(server2, options) {
 import { fileURLToPath } from "node:url";
 var E3_CLOUD_INDEX_PATH = fileURLToPath(new URL("../../index.json", import.meta.url));
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.91_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.93_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
 var SEARCH_TOOLS = ["mcp__plugin_east_east__search_east_examples", "mcp__plugin_east_east__get_east_example", "mcp__east__search_east_examples", "mcp__east__get_east_example"];
 
 // ../e3-cloud-plugin/dist/lib/names.js
@@ -23552,7 +23552,7 @@ var E3_CLOUD_PLUGIN = "e3-cloud";
 var E3_CLOUD_SERVER = "e3-cloud";
 var E3_CLOUD_SEARCH_TOOL = "search_e3_cloud_examples";
 var E3_CLOUD_GET_TOOL = "get_e3_cloud_example";
-var E3_CLOUD_PACKAGES = ["e3-cloud-ui", "e3-cloud-cli", "e3-cloud-client"];
+var E3_CLOUD_PACKAGES = ["e3-cloud-ui", "e3-cloud-files", "e3-cloud-cli", "e3-cloud-client"];
 var E3_CLOUD_CORPUS = "e3 cloud";
 var CLAUDE_TOOL_PREFIX = `mcp__plugin_${E3_CLOUD_PLUGIN}_${E3_CLOUD_SERVER}__`;
 var E3_CLOUD_GUIDANCE = {
@@ -23561,9 +23561,9 @@ var E3_CLOUD_GUIDANCE = {
   corpus: E3_CLOUD_CORPUS,
   scope: "@elaraai"
 };
-var E3_CLOUD_CODE = /@elaraai\/e3-cloud-(?:ui|client)\b/;
-var PACKAGE_PATH = /[/\\]node_modules[/\\]@elaraai[/\\]e3-cloud-(?:ui|cli|client)(?:[/\\]|$)/;
-var PACKAGE_PATTERN = /(?:^|[/\\])node_modules[/\\]@elaraai[/\\]e3-cloud-(?:ui|cli|client)(?:[/\\]|$)/;
+var E3_CLOUD_CODE = /@elaraai\/e3-cloud-(?:ui|files|client)\b/;
+var PACKAGE_PATH = /[/\\]node_modules[/\\]@elaraai[/\\]e3-cloud-(?:ui|files|cli|client)(?:[/\\]|$)/;
+var PACKAGE_PATTERN = /(?:^|[/\\])node_modules[/\\]@elaraai[/\\]e3-cloud-(?:ui|files|cli|client)(?:[/\\]|$)/;
 function isE3CloudCorpusRead(tool, input) {
   const text = (key) => typeof input[key] === "string" ? input[key] : "";
   return tool === "Read" ? PACKAGE_PATH.test(text("file_path")) : PACKAGE_PATH.test(text("path")) || PACKAGE_PATTERN.test(text("pattern"));
@@ -23585,7 +23585,7 @@ var E3_CLOUD_CODEX_SEARCH_GATE = {
   gateText: E3_CLOUD_SEARCH_GATE.gateText,
   readText: E3_CLOUD_READ_REMINDER.readText,
   isCorpusRead: isE3CloudCorpusRead,
-  shellSweep: /node_modules\/@elaraai\/e3-cloud-(?:ui|cli|client)\b/,
+  shellSweep: /node_modules\/@elaraai\/e3-cloud-(?:ui|files|cli|client)\b/,
   corpusCode: E3_CLOUD_CODE,
   markerPrefix: "e3-cloud-codex-search-",
   requireSearchEnv: "E3_CLOUD_REQUIRE_SEARCH"

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "e3-cloud-codex-plugin",
-  "version": "1.0.91",
-  "description": "e3 cloud - apps for hosted e3 workspaces with @elaraai/e3-cloud-ui, the e3-cloud CLI and @elaraai/e3-cloud-client: skills, example search and the search-first hooks",
+  "version": "1.0.93",
+  "description": "e3 cloud - apps for hosted e3 workspaces with @elaraai/e3-cloud-ui, files from buckets as inputs with @elaraai/e3-cloud-files, the e3-cloud CLI and @elaraai/e3-cloud-client: skills, example search and the search-first hooks",
   "author": {
     "name": "Elara AI",
     "email": "support@elara.ai",
@@ -22,7 +22,7 @@
   "interface": {
     "displayName": "e3 cloud",
     "shortDescription": "e3 cloud skills, example search and hooks.",
-    "longDescription": "e3 cloud - apps for hosted e3 workspaces with @elaraai/e3-cloud-ui, the e3-cloud CLI and @elaraai/e3-cloud-client: skills, example search and the search-first hooks",
+    "longDescription": "e3 cloud - apps for hosted e3 workspaces with @elaraai/e3-cloud-ui, files from buckets as inputs with @elaraai/e3-cloud-files, the e3-cloud CLI and @elaraai/e3-cloud-client: skills, example search and the search-first hooks",
     "developerName": "Elara AI",
     "category": "Productivity",
     "capabilities": [

package/README.md

@@ -1,7 +1,7 @@
 # e3 cloud plugin for Codex
 
-e3 cloud for Codex: the `e3-cloud-ui`, `e3-cloud-cli` and `e3-cloud-client`
-skills, the example search and the search-first hook, as the Claude Code
+e3 cloud for Codex: the `e3-cloud-ui`, `e3-cloud-files`, `e3-cloud-cli` and
+`e3-cloud-client` skills, the example search and the search-first hook, as the Claude Code
 plugin has them. Install it beside East's Codex plugin, which covers East, e3
 and e3-ui.
 
@@ -38,8 +38,8 @@ branch (`codex plugin marketplace add elaraai/plugins --ref beta`, named
 Codex runs one hook for every tool (east-plugin's `codexSearchGate` with e3
 cloud's names): after a search of e3 cloud's index or East's it records the
 search; before a call it reminds a read of
-`node_modules/@elaraai/e3-cloud-{ui,cli,client}`, and tells the first write of
-code importing `@elaraai/e3-cloud-ui` or `@elaraai/e3-cloud-client` with no
+`node_modules/@elaraai/e3-cloud-{ui,files,cli,client}`, and tells the first write of
+code importing `@elaraai/e3-cloud-ui`, `@elaraai/e3-cloud-files` or `@elaraai/e3-cloud-client` with no
 search recorded to search first (`E3_CLOUD_REQUIRE_SEARCH=deny`: a refusal).
 
 ## Developing it

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "e3 cloud plugin hooks: the search-before-coding gate for code using @elaraai/e3-cloud-ui or @elaraai/e3-cloud-client, and a reminder on reading their installed packages",
+  "description": "e3 cloud plugin hooks: the search-before-coding gate for code using @elaraai/e3-cloud-ui, @elaraai/e3-cloud-files or @elaraai/e3-cloud-client, and a reminder on reading their installed packages",
   "hooks": {
     "PreToolUse": [
       {

package/index.json

@@ -1,11 +1,12 @@
 {
   "version": 2,
   "stats": {
-    "totalEntries": 27,
-    "totalFiles": 1,
+    "totalEntries": 38,
+    "totalFiles": 2,
     "packages": {
       "e3-cloud-ui": 12,
-      "e3-cloud-cli": 11,
+      "e3-cloud-files": 10,
+      "e3-cloud-cli": 12,
       "e3-cloud-client": 4
     }
   },
@@ -233,6 +234,215 @@
       ],
       "source": "// Reading a record through one of its indexes, a page at a time: Data.bindPaged(orders, { index: byLine }) given the index's declaration, its rows the index key and the order's id\n// inputs: []\nconst Order = StructType({ line: StringType, qty: FloatType, status: StringType });\n\n/** A record of orders, changed only through its mutations. */\nconst orders = e3.record('orders', DictType(StringType, Order), new Map());\n\n/** The orders by line. */\nconst byLine = e3.recordIndex('by_line', orders,\n  { key: East.function([StringType, Order], StringType, (_$, _id, o) => o.line) });\n\nEast.function([], UIComponentType, _$ => (\n    <Reactive>{$ => {\n      const mine = $.let(Data.bindPaged(orders, { index: byLine }));\n      return <Table data={mine} columns={['ik', 'key']} />;\n    }}</Reactive>\n  ))"
     },
+    {
+      "id": "e3-cloud-files:decode.examples.ts:fileAsJson",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "packages/e3-cloud-files/test/decode.examples.ts",
+      "suite": "A file's bytes: file and latest",
+      "test": "A file input's bytes decoded as East's JSON, in the task that reads it: what upload.file('rates', { key: 'rates.json' }) or upload.latest(…) fills, a Blob",
+      "keywords": [
+        "Files",
+        "file",
+        "latest",
+        "Blob",
+        "decodeUtf8",
+        "parseJson",
+        "JSON",
+        "decode",
+        "task"
+      ],
+      "imports": [
+        "import { East, ArrayType, BlobType, DateTimeType, FloatType, IntegerType, StringType, StructType, example } from '@elaraai/east';",
+        "import { FilesFolderType, FilesListingType } from '@elaraai/e3-cloud-files';"
+      ],
+      "languages": [
+        "typescript"
+      ],
+      "source": "// A file input's bytes decoded as East's JSON, in the task that reads it: what upload.file('rates', { key: 'rates.json' }) or upload.latest(…) fills, a Blob\n// inputs: [utf8('[{\"currency\":\"AUD\",\"rate\":1.0},{\"currency\":\"USD\",\"rate\":0.66}]')]  returns: [{ currency: 'AUD', rate: 1.0 }, { currency: 'USD', rate: 0.66 }]\nconst Rate = StructType({ currency: StringType, rate: FloatType });\n\nEast.function([BlobType], ArrayType(Rate), (_$, file) => file.decodeUtf8().parseJson(ArrayType(Rate)))"
+    },
+    {
+      "id": "e3-cloud-files:decode.examples.ts:fileAsCsv",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "packages/e3-cloud-files/test/decode.examples.ts",
+      "suite": "A file's bytes: file and latest",
+      "test": "A file input's bytes decoded as CSV with a header row, each row a struct whose fields name the columns",
+      "keywords": [
+        "Files",
+        "file",
+        "latest",
+        "Blob",
+        "decodeCsv",
+        "CSV",
+        "header",
+        "delimiter",
+        "columns"
+      ],
+      "imports": [
+        "import { East, ArrayType, BlobType, DateTimeType, FloatType, IntegerType, StringType, StructType, example } from '@elaraai/east';",
+        "import { FilesFolderType, FilesListingType } from '@elaraai/e3-cloud-files';"
+      ],
+      "languages": [
+        "typescript"
+      ],
+      "source": "// A file input's bytes decoded as CSV with a header row, each row a struct whose fields name the columns\n// inputs: [utf8('tank,litres\\nT1,1200.5\\nT2,880\\n')]  returns: [{ tank: 'T1', litres: 1200.5 }, { tank: 'T2', litres: 880 }]\nconst Reading = StructType({ tank: StringType, litres: FloatType });\n\nEast.function([BlobType], ArrayType(Reading), (_$, file) => file.decodeCsv(Reading, { delimiter: ',' }))"
+    },
+    {
+      "id": "e3-cloud-files:decode.examples.ts:fileAsLines",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "packages/e3-cloud-files/test/decode.examples.ts",
+      "suite": "A file's bytes: file and latest",
+      "test": "A text file input's lines, trimmed, blank ones left out",
+      "keywords": [
+        "Files",
+        "file",
+        "Blob",
+        "decodeUtf8",
+        "split",
+        "lines",
+        "text",
+        "trim"
+      ],
+      "imports": [
+        "import { East, ArrayType, BlobType, DateTimeType, FloatType, IntegerType, StringType, StructType, example } from '@elaraai/east';",
+        "import { FilesFolderType, FilesListingType } from '@elaraai/e3-cloud-files';"
+      ],
+      "languages": [
+        "typescript"
+      ],
+      "source": "// A text file input's lines, trimmed, blank ones left out\n// inputs: [utf8('first\\n\\n  second  \\nthird\\n')]  returns: ['first', 'second', 'third']\nEast.function([BlobType], ArrayType(StringType), (_$, file) =>\n    file.decodeUtf8().split('\\n').map((_$, line) => line.trim()).filter((_$, line) => line.notEquals('')))"
+    },
+    {
+      "id": "e3-cloud-files:decode.examples.ts:folderAsOneArray",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "packages/e3-cloud-files/test/decode.examples.ts",
+      "suite": "A folder's files",
+      "test": "Every file of a folder input decoded and joined into one array, in the order of their paths: what upload.folder('orders', { prefix: 'orders/', include: '*.json' }) fills, a Dict<String, Blob> keyed by each file's path under the prefix",
+      "keywords": [
+        "Files",
+        "folder",
+        "Dict",
+        "Blob",
+        "flattenToArray",
+        "parseJson",
+        "every file",
+        "concatenate"
+      ],
+      "imports": [
+        "import { East, ArrayType, BlobType, DateTimeType, FloatType, IntegerType, StringType, StructType, example } from '@elaraai/east';",
+        "import { FilesFolderType, FilesListingType } from '@elaraai/e3-cloud-files';"
+      ],
+      "languages": [
+        "typescript"
+      ],
+      "source": "// Every file of a folder input decoded and joined into one array, in the order of their paths: what upload.folder('orders', { prefix: 'orders/', include: '*.json' }) fills, a Dict<String, Blob> keyed by each file's path under the prefix\n// inputs: [new Map([\n    ['2026-10-01.json', utf8('[{\"id\":\"O-1\",\"sku\":\"A1\",\"amount\":250.0}]')],\n    ['2026-10-02.json', utf8('[{\"id\":\"O-2\",\"sku\":\"B2\",\"amount\":80.0},{\"id\":\"O-3\",\"sku\":\"A1\",\"amount\":120.0}]')],\n  ])]  returns: [{ id: 'O-1', sku: 'A1', amount: 250 }, { id: 'O-2', sku: 'B2', amount: 80 }, { id: 'O-3', sku: 'A1', amount: 120 }]\nconst Order = StructType({ id: StringType, sku: StringType, amount: FloatType });\n\nEast.function([FilesFolderType], ArrayType(Order), (_$, files) =>\n    files.flattenToArray((_$, file) => file.decodeUtf8().parseJson(ArrayType(Order))))"
+    },
+    {
+      "id": "e3-cloud-files:decode.examples.ts:folderRowsWithTheirFile",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "packages/e3-cloud-files/test/decode.examples.ts",
+      "suite": "A folder's files",
+      "test": "Every CSV file of a folder input decoded, each row carrying the path of the file it came from",
+      "keywords": [
+        "Files",
+        "folder",
+        "path",
+        "key",
+        "flattenToArray",
+        "decodeCsv",
+        "which file",
+        "provenance"
+      ],
+      "imports": [
+        "import { East, ArrayType, BlobType, DateTimeType, FloatType, IntegerType, StringType, StructType, example } from '@elaraai/east';",
+        "import { FilesFolderType, FilesListingType } from '@elaraai/e3-cloud-files';"
+      ],
+      "languages": [
+        "typescript"
+      ],
+      "source": "// Every CSV file of a folder input decoded, each row carrying the path of the file it came from\n// inputs: [new Map([\n    ['site-a.csv', utf8('tank,litres\\nT1,1200.5\\n')],\n    ['site-b.csv', utf8('tank,litres\\nT9,40\\n')],\n  ])]  returns: [{ file: 'site-a.csv', tank: 'T1', litres: 1200.5 }, { file: 'site-b.csv', tank: 'T9', litres: 40 }]\nconst Reading = StructType({ tank: StringType, litres: FloatType });\n\nEast.function([FilesFolderType], ArrayType(StructType({ file: StringType, tank: StringType, litres: FloatType })), (_$, files) =>\n    files.flattenToArray((_$, file, path) =>\n      file.decodeCsv(Reading, { delimiter: ',' }).map((_$, row) => ({ file: path, tank: row.tank, litres: row.litres }))))"
+    },
+    {
+      "id": "e3-cloud-files:decode.examples.ts:folderUnderASubfolder",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "packages/e3-cloud-files/test/decode.examples.ts",
+      "suite": "A folder's files",
+      "test": "Only the files of a folder input under one of its subfolders. A folder declared with include '**/*.csv', or none, holds its subfolders' files too, each path naming its subfolder (2026/10/a.csv); '*.csv' matches only the top level",
+      "keywords": [
+        "Files",
+        "folder",
+        "filter",
+        "startsWith",
+        "path",
+        "subfolder",
+        "include",
+        "**"
+      ],
+      "imports": [
+        "import { East, ArrayType, BlobType, DateTimeType, FloatType, IntegerType, StringType, StructType, example } from '@elaraai/east';",
+        "import { FilesFolderType, FilesListingType } from '@elaraai/e3-cloud-files';"
+      ],
+      "languages": [
+        "typescript"
+      ],
+      "source": "// Only the files of a folder input under one of its subfolders. A folder declared with include '**/*.csv', or none, holds its subfolders' files too, each path naming its subfolder (2026/10/a.csv); '*.csv' matches only the top level\n// inputs: [new Map([['2025/12/a.csv', utf8('a')], ['2026/01/b.csv', utf8('b')], ['2026/02/c.csv', utf8('c')]]), '2026/']  returns: new Map([['2026/01/b.csv', utf8('b')], ['2026/02/c.csv', utf8('c')]])\nEast.function([FilesFolderType, StringType], FilesFolderType, (_$, files, under) =>\n    files.filter((_$, _file, path) => path.startsWith(under)))"
+    },
+    {
+      "id": "e3-cloud-files:decode.examples.ts:listingChangedSince",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "packages/e3-cloud-files/test/decode.examples.ts",
+      "suite": "A listing: the files, without their bytes",
+      "test": "The paths of a listing input's files changed since a time, without reading their bytes: what upload.listing('order_files', { prefix: 'orders/' }) fills, each file's size, modified time and ETag by its path",
+      "keywords": [
+        "Files",
+        "listing",
+        "modified",
+        "since",
+        "DateTime",
+        "filter",
+        "keys",
+        "newest"
+      ],
+      "imports": [
+        "import { East, ArrayType, BlobType, DateTimeType, FloatType, IntegerType, StringType, StructType, example } from '@elaraai/east';",
+        "import { FilesFolderType, FilesListingType } from '@elaraai/e3-cloud-files';"
+      ],
+      "languages": [
+        "typescript"
+      ],
+      "source": "// The paths of a listing input's files changed since a time, without reading their bytes: what upload.listing('order_files', { prefix: 'orders/' }) fills, each file's size, modified time and ETag by its path\n// inputs: [\n    new Map([\n      ['2026-10-01.json', { size: 120n, modified: new Date(Date.UTC(2026, 9, 1)), etag: 'a1' }],\n      ['2026-10-02.json', { size: 310n, modified: new Date(Date.UTC(2026, 9, 2)), etag: 'b2' }],\n    ]),\n    new Date(Date.UTC(2026, 9, 1, 12)),\n  ]  returns: ['2026-10-02.json']\nEast.function([FilesListingType, DateTimeType], ArrayType(StringType), (_$, rows, since) =>\n    rows.filter((_$, row) => row.modified.greaterThan(since)).keys().toArray())"
+    },
+    {
+      "id": "e3-cloud-files:decode.examples.ts:listingTotals",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "packages/e3-cloud-files/test/decode.examples.ts",
+      "suite": "A listing: the files, without their bytes",
+      "test": "How many files a listing input holds, and their bytes in all",
+      "keywords": [
+        "Files",
+        "listing",
+        "size",
+        "sum",
+        "count",
+        "bytes",
+        "how many"
+      ],
+      "imports": [
+        "import { East, ArrayType, BlobType, DateTimeType, FloatType, IntegerType, StringType, StructType, example } from '@elaraai/east';",
+        "import { FilesFolderType, FilesListingType } from '@elaraai/e3-cloud-files';"
+      ],
+      "languages": [
+        "typescript"
+      ],
+      "source": "// How many files a listing input holds, and their bytes in all\n// inputs: [new Map([\n    ['a.json', { size: 120n, modified: new Date(Date.UTC(2026, 9, 1)), etag: 'a1' }],\n    ['b.json', { size: 310n, modified: new Date(Date.UTC(2026, 9, 2)), etag: 'b2' }],\n  ])]  returns: { files: 2n, bytes: 430n }\nEast.function([FilesListingType], StructType({ files: IntegerType, bytes: IntegerType }), (_$, rows) =>\n    ({ files: rows.size(), bytes: rows.sum((_$, row) => row.size) }))"
+    },
     {
       "id": "e3-cloud-ui:static:app",
       "skill": "e3-cloud-ui",
@@ -347,6 +557,70 @@
         "typescript"
       ]
     },
+    {
+      "id": "e3-cloud-files:static:declare",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "static",
+      "suite": "Files",
+      "test": "Declaring which inputs a bucket's files fill: a source, one file, the newest of a folder, every file of a folder and a folder's listing, each an ordinary e3.input a task takes, and the declarations e3-cloud files deploy deploys",
+      "keywords": [
+        "Files",
+        "Files.source",
+        "file",
+        "latest",
+        "folder",
+        "listing",
+        "Files.manifest",
+        "include",
+        "glob",
+        "prefix",
+        "key",
+        "s3",
+        "bucket",
+        "input",
+        "Blob",
+        "e3-cloud-files"
+      ],
+      "imports": [
+        "import { East, ArrayType, BlobType, FloatType, StringType, StructType } from '@elaraai/east';",
+        "import e3, { type Runner } from '@elaraai/e3';",
+        "import { Files, FilesFolderType } from '@elaraai/e3-cloud-files';"
+      ],
+      "source": "// src/files.ts: which inputs a source's files fill. Each workspace binds the source to s3://bucket/prefix/;\n// keys and prefixes here are relative to it, so the code never names a bucket\nexport const upload = Files.source('upload');\nexport const rates = upload.file('rates', { key: 'rates.json' });                          // Blob\nexport const stock = upload.latest('stock', { prefix: 'stock/', include: '*.json' });     // Blob: the greatest key, so name files by date\nexport const orders = upload.folder('orders', { prefix: 'orders/', include: '*.json' });  // Dict<String, Blob>, by path under the prefix\nexport const orderFiles = upload.listing('order_files', { prefix: 'orders/' });           // each file's size, modified and etag, no bytes\n// '*.json' is the prefix's own files; '**/*.json' takes its subfolders' too\nexport default Files.manifest([upload]);\n\n// src/package.ts: each is an ordinary input, unassigned until a sync sets it; a task decodes what arrives\nconst runner: Runner = { runtime: 'east-c', platforms: ['east-c-std'] };\nconst Rate = StructType({ currency: StringType, rate: FloatType });\nconst Order = StructType({ id: StringType, sku: StringType, amount: FloatType });\nexport const rateTable = e3.task('rate_table', [rates],\n  East.function([BlobType], ArrayType(Rate), (_$, file) => file.decodeUtf8().parseJson(ArrayType(Rate))), { runner });\nexport const allOrders = e3.task('all_orders', [orders],\n  East.function([FilesFolderType], ArrayType(Order), (_$, files) =>\n    files.flattenToArray((_$, file) => file.decodeUtf8().parseJson(ArrayType(Order)))), { runner });\nexport default e3.package('orders', '1.0.0', rateTable, allOrders);",
+      "languages": [
+        "typescript"
+      ]
+    },
+    {
+      "id": "e3-cloud-files:static:test-sync",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "static",
+      "suite": "syncFiles",
+      "test": "Testing a solution's Files without a bucket: its declarations synced from a bucket in memory into a workspace in memory, then its task's function run on what came in",
+      "keywords": [
+        "syncFiles",
+        "MemoryBucket",
+        "MemoryWorkspace",
+        "MemoryLedger",
+        "test",
+        "sync",
+        "report",
+        "unit test",
+        "@elaraai/e3-cloud-files/sync"
+      ],
+      "imports": [
+        "import { East, none } from '@elaraai/east';",
+        "import { MemoryBucket, MemoryLedger, MemoryWorkspace, syncFiles } from '@elaraai/e3-cloud-files/sync';",
+        "import declarations from '../src/files.js';",
+        "import { decodeRates } from '../src/package.js';"
+      ],
+      "source": "const bucket = new MemoryBucket();\nbucket.put('drop/rates.json', '[{\"currency\":\"AUD\",\"rate\":1.0}]');\nconst workspace = new MemoryWorkspace();\nconst report = await syncFiles({\n  manifest: declarations,\n  bindings: [{ source: 'upload', url: 's3://any-bucket/drop/', region: none, profile: none, latest: none }],\n  reader: () => bucket.reader('drop/'),   // the bucket, under the binding's prefix\n  writer: workspace,\n  ledger: new MemoryLedger(),             // what each input took: a second sync reads nothing unchanged\n  inputs: ['rates'],\n});\n// report.mappings: per input, the files added, changed, removed, unchanged and refused, and whether it was written\nconst rates = East.compile(decodeRates, [])(workspace.files.get('rates')!);",
+      "languages": [
+        "typescript"
+      ]
+    },
     {
       "id": "e3-cloud-cli:static:sign-in",
       "skill": "e3-cloud-cli",
@@ -633,6 +907,34 @@
         "typescript"
       ]
     },
+    {
+      "id": "e3-cloud-cli:static:files",
+      "skill": "e3-cloud-cli",
+      "package": "e3-cloud-cli",
+      "file": "static",
+      "suite": "e3-cloud files",
+      "test": "Bringing a bucket's files into a workspace: deploy the declarations, bind each source to s3://bucket/prefix/, sync what changed, then run the dataflow; locally with your own cloud profile, the bytes only in the local repository",
+      "keywords": [
+        "files",
+        "deploy",
+        "bind",
+        "sync",
+        "status",
+        "s3",
+        "bucket",
+        "--profile",
+        "--latest",
+        "--dry-run",
+        "--input",
+        "e3 dataflow run",
+        "e3-cloud"
+      ],
+      "imports": [],
+      "source": "e3 workspace deploy ./repo dev --from-source src/package.ts\ne3-cloud files deploy ./repo dev src/files.ts --dry-run          # checked against the package dev runs; changes nothing\ne3-cloud files deploy ./repo dev src/files.ts\ne3-cloud files bind ./repo dev upload s3://partner-drop/orders/ --profile partner --latest 30   # locally: your own profile, each folder's 30 newest\ne3-cloud files sync ./repo dev --dry-run                         # what a sync would take\ne3-cloud files sync ./repo dev                                   # reads only files whose ETag or size changed\ne3-cloud files status ./repo dev                                 # declarations, bindings, the last sync\ne3 dataflow run ./repo dev                                       # a sync doesn't run the dataflow\n# <repo> may be a repository URL instead (https://e3.example.com/repos/acme): the same commands, run by the platform",
+      "languages": [
+        "typescript"
+      ]
+    },
     {
       "id": "e3-cloud-client:static:basics",
       "skill": "e3-cloud-client",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elaraai/e3-cloud-codex-plugin",
-  "version": "1.0.91",
-  "description": "e3 cloud - apps for hosted e3 workspaces with @elaraai/e3-cloud-ui, the e3-cloud CLI and @elaraai/e3-cloud-client: skills, example search and the search-first hooks",
+  "version": "1.0.93",
+  "description": "e3 cloud - apps for hosted e3 workspaces with @elaraai/e3-cloud-ui, files from buckets as inputs with @elaraai/e3-cloud-files, the e3-cloud CLI and @elaraai/e3-cloud-client: skills, example search and the search-first hooks",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "author": {

package/skills/e3-cloud-cli/SKILL.md

@@ -1,24 +1,25 @@
 ---
 name: e3-cloud-cli
-description: "The e3-cloud CLI — run an e3 cloud deployment from the shell. Use when: (1) Signing in (`e3 auth login` to a server, whose credentials e3-cloud shares) and checking who you are (`e3-cloud whoami`), (2) Building and deploying apps — `e3-cloud app build`, `app deploy` (UI-only, or with its package, `--dry-run`, several together, `--from-source`), `app list`, `app versions`, `app remove` (an app is developed in the cloud: deployed to a workspace of one's own and opened there), (3) Staging an app for the platform's next e3 (`app deploy --for-platform VERSION`, `app list-all`), (4) Staging and releases — `e3-cloud staging add|stop|list` (a staging protects the workspace it releases to: it then changes only by a release from it, or a rollback; `--force` on `app deploy` and `app remove` is an admin's override), `e3 workspace copy` for the rehearsal, `e3-cloud release URL FROM TO` with `--plan`, `--carry` and `--remove-apps`,… See the detailed scope below."
+description: "The e3-cloud CLI — run an e3 cloud deployment from the shell. Use when: (1) Signing in (`e3 auth login` to a server, whose credentials e3-cloud shares) and checking who you are (`e3-cloud whoami`), (2) Building and deploying apps — `e3-cloud app build`, `app deploy` (UI-only, or with its package, `--dry-run`, several together, `--from-source`), `app list`, `app versions`, `app remove` (an app is developed in the cloud: deployed to a workspace of one's own and opened there), (3) Staging an app for the platform's next e3 (`app deploy --for-platform VERSION`, `app list-all`), (4) Staging and releases — `e3-cloud staging add|stop|list` (a staging protects the workspace it releases to: it then changes only by a release from it, or a rollback; `--force` on `app deploy` and `app remove` is an admin's override), `e3 workspace copy` for the rehearsal, `e3-cloud release URL FROM TO` with `--plan`, `--carry` and `--remove-apps` (a… See the detailed scope below."
 ---
 
 ## Detailed skill scope
 
-The e3-cloud CLI — run an e3 cloud deployment from the shell. Use when: (1) Signing in (`e3 auth login` to a server, whose credentials e3-cloud shares) and checking who you are (`e3-cloud whoami`), (2) Building and deploying apps — `e3-cloud app build`, `app deploy` (UI-only, or with its package, `--dry-run`, several together, `--from-source`), `app list`, `app versions`, `app remove` (an app is developed in the cloud: deployed to a workspace of one's own and opened there), (3) Staging an app for the platform's next e3 (`app deploy --for-platform VERSION`, `app list-all`), (4) Staging and releases — `e3-cloud staging add|stop|list` (a staging protects the workspace it releases to: it then changes only by a release from it, or a rollback; `--force` on `app deploy` and `app remove` is an admin's override), `e3 workspace copy` for the rehearsal, `e3-cloud release URL FROM TO` with `--plan`, `--carry` and `--remove-apps`, `e3-cloud history`, `e3-cloud rollback`, (5) A repository's people and business roles — `e3-cloud user list|add|remove` (`--role owner`, or a user with `--roles 'Rostering,Finance'`), `e3-cloud role list|show|set|rm` (`--grant WORKSPACE/APP[:page,page]`), and for admins `user list-all|disable|enable|invitations|uninvite`, (6) Secrets (`e3-cloud secrets set|list|rm`), schedules (`schedule set|get|list|remove`), each task's compute size and timeout (`compute`, `timeout`), people's workspace settings (`settings`), (7) Records' history, rollback and backups (`e3-cloud records …`) and feedback (`e3-cloud feedback …`).
+The e3-cloud CLI — run an e3 cloud deployment from the shell. Use when: (1) Signing in (`e3 auth login` to a server, whose credentials e3-cloud shares) and checking who you are (`e3-cloud whoami`), (2) Building and deploying apps — `e3-cloud app build`, `app deploy` (UI-only, or with its package, `--dry-run`, several together, `--from-source`), `app list`, `app versions`, `app remove` (an app is developed in the cloud: deployed to a workspace of one's own and opened there), (3) Staging an app for the platform's next e3 (`app deploy --for-platform VERSION`, `app list-all`), (4) Staging and releases — `e3-cloud staging add|stop|list` (a staging protects the workspace it releases to: it then changes only by a release from it, or a rollback; `--force` on `app deploy` and `app remove` is an admin's override), `e3 workspace copy` for the rehearsal, `e3-cloud release URL FROM TO` with `--plan`, `--carry` and `--remove-apps` (a release carries the package, the apps and the Files declarations; the target keeps its data and bindings), `e3-cloud history`, `e3-cloud rollback`, (5) A repository's people and business roles — `e3-cloud user list|add|remove` (`--role owner`, or a user with `--roles 'Rostering,Finance'`), `e3-cloud role list|show|set|rm` (`--grant WORKSPACE/APP[:page,page]`), and for admins `user list-all|disable|enable|invitations|uninvite`, (6) Secrets (`e3-cloud secrets set|list|rm`), schedules (`schedule set|get|list|remove`), each task's compute size and timeout (`compute`, `timeout`), people's workspace settings (`settings`), (7) Records' history, rollback and backups (`e3-cloud records …`) and feedback (`e3-cloud feedback …`), (8) Files — a solution's inputs from files in a bucket: `e3-cloud files deploy|bind|sync|status`, given a local repository's path or a repository URL (the e3-cloud-files skill declares and decodes them), (9) Walking a solution through its life, step by step — starting it, adding a staging, developing an app's pages, changing the package's tasks and inputs, migrating a record, Files, rehearsing and releasing, rolling back, an emergency change to production, people and roles, schedules, secrets and compute, feedback, the platform's next e3, and retiring an app or a workspace.
 
 # e3-cloud — the e3 cloud CLI (@elaraai/e3-cloud-cli)
 
 `e3-cloud` runs the parts of an e3 cloud deployment that e3's own CLI does not:
 apps, releases, users and roles, secrets, schedules, task configs, records'
-history and backups, and feedback. e3's CLI (`e3`, `@elaraai/e3-cli`) still
+history and backups, feedback, and files from buckets. e3's CLI (`e3`, `@elaraai/e3-cli`) still
 does what it does against any server: repositories, packages, workspaces,
 datasets, dataflow runs and copies. Both sign in with `e3 auth login` and share its
 credentials (`~/.e3/credentials.json`).
 
 A command names what it acts on by URL: a server (`https://e3.example.com`),
 a repository (`…/repos/acme`), or a workspace (`…/repos/acme/workspaces/production`),
-as its help says.
+as its help says. `e3-cloud files` takes a local repository's path instead
+as readily.
 
 ## Before writing code — search the example index
 
@@ -54,8 +55,284 @@ e3-cloud staging add https://e3.example.com/repos/acme production staging
 # A release: the plan first, then exactly what staging runs, production's data kept
 e3-cloud release https://e3.example.com/repos/acme staging production --plan
 e3-cloud release https://e3.example.com/repos/acme staging production
+e3 dataflow run https://e3.example.com/repos/acme production    # a release runs nothing
 ```
 
+## Lifecycle guides
+
+Each guide is the commands in order, then what to watch. `URL` stands for a
+repository's URL (`https://e3.example.com/repos/acme`); a workspace's URL is
+`URL/workspaces/<name>`.
+
+```
+What are you doing?
+├─ Setting up
+│   ├─ A new solution in the cloud                    → 1. Start a solution
+│   └─ Production, and a staging to try changes in    → 2. Add a staging
+├─ Changing the solution (always in staging)
+│   ├─ An app's pages or menus                        → 3. Develop an app
+│   ├─ Tasks, inputs or functions                     → 4. Change the package
+│   ├─ A record's type, or its values                 → 5. Migrate a record
+│   └─ Which inputs come from files                   → 6. Files
+├─ Shipping to production
+│   ├─ Rehearse on production's data, then release    → 7. Rehearse and release
+│   ├─ Bring reference data set up in staging         → 7, --carry
+│   ├─ Undo a release                                 → 8. Roll back
+│   └─ A fix that can't wait for staging              → 9. An emergency change
+├─ Running it
+│   ├─ Who may use which apps and pages               → 10. People and roles
+│   ├─ Runs on a timetable, credentials, task sizes   → 11. Schedules, secrets, compute
+│   ├─ What users report from the pages               → 12. Feedback
+│   └─ A record someone got wrong                     → 5, record rollback and backups
+└─ Changing the platform, or ending things
+    ├─ The platform's next e3                         → 13. The platform's next e3
+    └─ An app or a workspace no longer needed         → 14. Retire
+```
+
+### 1. Start a solution
+
+```bash
+e3 auth login https://e3.example.com
+e3 repo create URL
+e3 workspace deploy URL production --from-source src/package.ts   # makes the workspace
+e3-cloud user add URL ana@example.com --role owner
+e3-cloud app deploy URL production --from-source src/apps/ops.tsx
+e3 dataflow run URL production
+```
+
+- A repository holds one solution; a workspace runs one version of its
+  package, with its own data.
+- Add a staging (2) before anyone relies on production: from then on every
+  change goes through it.
+
+### 2. Add a staging
+
+```bash
+e3-cloud staging add URL production staging --plan
+e3-cloud staging add URL production staging
+e3-cloud staging list URL
+```
+
+- The staging starts as a copy of production, data included: its package,
+  inputs, records, apps, task settings and Files (declarations, bindings and
+  what each input took). `--as-is` makes a workspace there the staging as it
+  stands; `--replace` copies over one.
+- Production is then protected: its package, apps and Files declarations
+  change only by a release from its staging, or a rollback. People go on
+  using it: inputs, records, runs and schedules.
+- Only an admin stops a staging (`staging stop URL production`), which
+  deletes nothing and unprotects production.
+
+### 3. Develop an app
+
+```bash
+e3-cloud app deploy URL staging --from-source src/apps/ops.tsx --dry-run
+e3-cloud app deploy URL staging --from-source src/apps/ops.tsx
+e3-cloud app list URL staging
+e3-cloud app versions URL staging ops
+```
+
+- Apps are developed in the cloud: deploy to staging (or a workspace of your
+  own) after each change, and open it in the console. Nothing serves an app
+  locally.
+- An app is checked against the package it was built against. When staging
+  runs that package, only the app changes; otherwise the package deploys
+  first, keeping the inputs people set, and the app goes live as it
+  completes.
+- Several apps deploy together or not at all: `--from-source a.tsx b.tsx`.
+  Writing pages and menus: the e3-cloud-ui skill.
+
+### 4. Change the package
+
+```bash
+e3 workspace deploy URL staging --from-source src/package.ts --inputs keep-edited --plan
+e3 workspace deploy URL staging --from-source src/package.ts --inputs keep-edited
+e3 dataflow run URL staging
+```
+
+- `--plan` says what the deploy does to each record, index and input, and
+  writes nothing. `--inputs keep-edited` keeps the inputs people set while
+  their type is unchanged; the default resets every input to the package's.
+- A deploy that would break an app of the workspace is refused, naming each
+  app's problems: rebuild the apps against the new package and deploy them
+  with it (`e3-cloud app deploy … --from-source`, which deploys the package
+  first).
+- A deploy runs nothing: the next run recomputes the tasks. Files
+  declarations that no longer fit the package make a sync refuse until
+  they're deployed again (6).
+
+### 5. Migrate a record
+
+A record's new type comes with a migration in the package: e3's
+`e3.migration.value`, `rows` or `rekey`, each step naming the one before it
+with `after` (the e3 skill). Then, in staging:
+
+```bash
+e3-cloud records backup URL staging orders --note "before orders v2"
+e3 workspace deploy URL staging --from-source src/package.ts --inputs keep-edited --plan   # orders: migrate (1 step)
+e3 workspace deploy URL staging --from-source src/package.ts --inputs keep-edited
+e3-cloud records backup URL production orders --note "before the release of orders v2"
+e3-cloud release URL staging production --plan                                           # orders migrates (1 step)
+```
+
+- A deploy runs only the steps a workspace hasn't applied: production runs
+  them as the release deploys.
+- A migration is one way. A rollback past it is refused, and so is a restore
+  of a backup from before it, so back production up and rehearse first (7).
+- Fixing a record's values needs no deploy: `records history` (who changed
+  what, and when), `records show URL ws orders COMMIT` (its value then),
+  `records rollback URL ws orders COMMIT` (an audited `$rollback` commit;
+  `--expect-head` refuses if it moved meanwhile), `records restore URL ws
+  orders BACKUP_ID`.
+- A deploy's `--schema fail` refuses rather than migrate; `--schema reset`
+  gives the record the package's initial value, its data lost.
+
+### 6. Files
+
+```bash
+e3-cloud files deploy URL staging src/files.ts
+e3-cloud files bind   URL staging upload s3://bucket/acme/staging/
+e3-cloud files sync   URL staging
+e3 dataflow run URL staging
+```
+
+- The declarations (which inputs files fill) travel with releases; where
+  each source's files are (its binding) is each workspace's own. A staging
+  copied from production reads production's files until bound elsewhere.
+- Before a release whose declarations read a source production hasn't bound,
+  bind it there: `files bind URL production invoices s3://…`. The release is
+  refused until then.
+- A release syncs nothing: after it, `files sync URL production`, then run
+  production. Production refuses `files deploy` (9 for the exception).
+  Declaring and decoding the files: the e3-cloud-files skill.
+
+### 7. Rehearse and release
+
+```bash
+e3 workspace copy URL production staging            # staging becomes production as it is now
+# … the change in staging (3–6), a run, a look in the console …
+e3-cloud release URL staging production --plan
+e3-cloud release URL staging production
+e3-cloud files sync URL production                  # when Files changed
+e3 dataflow run URL production
+```
+
+- A release gives production exactly what staging runs: the package and app
+  versions by hash, the Files declarations, and the bundles staged for the
+  next e3. Production keeps its data (inputs people set kept, records
+  migrated), its bindings, schedules, task settings and people.
+- The plan names the package, each app, record, input and Files input, the
+  apps' checks, and any admin change it undoes. A refused plan says why and
+  changes nothing; one that would change nothing is refused too.
+- `--carry inputs/mappings` brings reference data set up in staging: an
+  input, or a record new in the release (a record production has is never
+  overwritten). `--remove-apps` removes production's apps staging lacks.
+- A release that changes the package runs a deploy job, which the CLI waits
+  for. Only production's staging releases to it, and owners and admins
+  release.
+
+### 8. Roll back
+
+```bash
+e3-cloud history URL production
+e3-cloud rollback URL production --plan          # the newest earlier state
+e3-cloud rollback URL production 41              # an entry, by its id
+```
+
+- A rollback releases an entry again: its package, apps and Files
+  declarations exactly. It undoes no data: inputs, records and runs stay.
+- It is refused past a record migration (e3 never migrates a record back) and
+  for an app version the repository no longer keeps; the plan says which.
+- Fix forward in staging afterwards: the next release brings staging's state
+  back to production.
+
+### 9. An emergency change
+
+```bash
+e3-cloud app deploy URL production --from-source src/apps/ops.tsx --force
+e3-cloud files deploy URL production src/files.ts --force
+e3-cloud app remove URL production legacy --force
+```
+
+- Admins only. Each warns first and lands in production's history as an
+  admin override.
+- The next release from staging undoes it, and its plan says so: make the
+  same change in staging before then.
+- No force deploys a package to production: release it from staging, or roll
+  back (8).
+
+### 10. People and roles
+
+```bash
+e3-cloud role set URL Rostering --grant production/ops:roster,leave
+e3-cloud user add URL sam@example.com --roles 'Rostering'
+e3-cloud user add URL ana@example.com --role owner
+e3-cloud user list URL
+```
+
+- An owner manages the repository; a user reaches only the apps and pages
+  their business roles grant (`--grant WORKSPACE/APP`, its pages after a
+  colon; the built-in `All apps` grants every live app).
+- Adding someone who hasn't signed in yet invites them, and the grant is
+  theirs at first sign-in. Admins: `user invitations`, `uninvite`,
+  `disable`, `enable`, `list-all`.
+- Testers of staging need a role granting staging's apps; owners and admins
+  reach them already.
+
+### 11. Schedules, secrets and compute
+
+```bash
+e3-cloud schedule set URL/workspaces/production --cron "0 2 * * *" --timezone Australia/Sydney
+e3-cloud secrets set URL PARTNER_API_KEY < key.txt
+e3-cloud compute set URL/workspaces/production forecast --size medium
+e3-cloud timeout set URL/workspaces/production forecast --timeout 2h
+```
+
+- A schedule runs its workspace's dataflow; each workspace has its own, and
+  releases and copies leave it as it is.
+- Secrets are the repository's: every workspace's tasks read them by name
+  (`Env.get("NAME")`), and the next run reads a new value. Values are never
+  shown again.
+- A task's compute size and timeout are its workspace's: a copy brings the
+  source's, a release leaves the target's.
+
+### 12. Feedback
+
+```bash
+e3-cloud feedback enable URL/workspaces/production
+e3-cloud feedback list   URL/workspaces/production
+e3-cloud feedback show   URL/workspaces/production 12
+e3-cloud feedback close  URL/workspaces/production 12
+```
+
+- Users send notes about any part of a page, with a screenshot and the data
+  behind the view. Owners and admins read and close them; each sender reads
+  their own (`feedback list --mine`).
+
+### 13. The platform's next e3
+
+```bash
+e3-cloud app list-all https://e3.example.com                           # admins: which apps need a bundle
+e3-cloud app deploy URL staging --from-source src/apps/ops.tsx --for-platform 1.0.93
+e3-cloud release URL staging production
+```
+
+- Build with the next release's packages and stage the bundle beside the
+  live app: it goes live when the platform moves to that e3. A release
+  carries staging's staged bundles, so production gets them through its
+  staging.
+
+### 14. Retire
+
+```bash
+e3-cloud app remove URL staging legacy
+e3-cloud release URL staging production --remove-apps
+```
+
+- A workspace with apps isn't removed: remove its apps first. Neither is a
+  staging, or a workspace a staging protects: an admin stops the staging
+  first (`staging stop`). Then `e3 workspace remove URL old`.
+
 ## Apps
 
 - `app build <source>` writes the bundle (`dist/<app>.app`): the app and the
@@ -81,8 +358,9 @@ e3-cloud release https://e3.example.com/repos/acme staging production
 
 A workspace's staging is where changes are tried before they reach the
 workspace people use, which it then **protects**, as a protected branch is
-protected: its package and apps change only by a release from its staging, or
-a rollback. One staging to a workspace; no staging has one of its own.
+protected: its package, apps and Files declarations change only by a release
+from its staging, or a rollback. One staging to a workspace; no staging has
+one of its own.
 
 - `staging add <repo-url> <live> <name>` prints what it would do, then adds it:
   a copy of the live workspace as it is now, data included. `--plan` stops at
@@ -92,16 +370,17 @@ a rollback. One staging to a workspace; no staging has one of its own.
   `staging stop <repo-url> <live>` (admins alone) unprotects it, deleting
   nothing.
 - A protected workspace refuses e3's `workspace deploy`, an app deploy or
-  removal, a copy onto it, and its removal or its staging's. Its data goes on:
-  inputs, records, runs and schedules.
+  removal, a Files deploy, a copy onto it, and its removal or its staging's.
+  Its data goes on: inputs, records, runs and schedules, and its Files
+  bindings and syncs.
 
 ## Releases
 
 A release gives the target exactly the package and app versions the source
-runs, by hash, with the bundles it has staged for the next e3. Only the
-target's staging releases to it. The target keeps the inputs people set in it,
-migrates its records, and runs next by hand or on its schedule. Owners and
-admins release.
+runs, by hash, with the bundles it has staged for the next e3 and its Files
+declarations. Only the target's staging releases to it. The target keeps the
+inputs people set in it and where its files come from, migrates its records,
+and runs next by hand or on its schedule. Owners and admins release.
 
 - `e3 workspace copy <repo-url> production staging` makes staging production
   as it is now, apps included: the rehearsal's first step before each change.
@@ -112,8 +391,31 @@ admins release.
   from the source by reference; `--remove-apps` removes the target's apps the
   source lacks.
 - `history <repo-url> <workspace>` lists each release, deploy, app deploy,
-  copy and rollback, with its id; `rollback <repo-url> <workspace> [<id>]`
-  releases an entry again, its package and apps exactly.
+  copy, rollback, Files deploy and source bound, with its id; `rollback
+  <repo-url> <workspace> [<id>]` releases an entry again, its package, apps
+  and Files declarations exactly.
+
+## Files
+
+A solution declares in its code which of its inputs come from files in a
+bucket (`@elaraai/e3-cloud-files`, its own skill). The CLI deploys the
+declarations, binds each source and syncs, given a local repository's path or
+a repository URL:
+
+- `files deploy <repo> <ws> <source>` runs the source (its default export is
+  `Files.manifest(...)`) and checks the declarations against the package the
+  workspace runs; `--dry-run` keeps nothing. A protected workspace refuses
+  it: its declarations come by a release (`--force`, an admin's override).
+- `files bind <repo> <ws> <source> s3://bucket/prefix/` says where a source's
+  files are; `--region` when the bucket's isn't yours. Locally only:
+  `--profile` (the profile to read with), `--latest n` (each folder's n
+  greatest keys). A workspace's bindings are its own: a release never
+  changes them, and a source may be bound before a release brings the
+  declarations that read it.
+- `files sync <repo> <ws>` reads only files whose ETag or size changed and
+  writes only inputs whose files changed; `--input`, `--dry-run`. It doesn't
+  run the dataflow: `e3 dataflow run` does, and the sync prints the command.
+- `files status <repo> <ws>`: the declarations, the bindings, the last sync.
 
 ## Traps
 
@@ -122,7 +424,11 @@ admins release.
   release (deploy the source again).
 - A rollback past a record migration is refused: e3's deploy never migrates a
   record back. A rollback stays open on a protected workspace.
-- Sign in with `e3 auth login <server>`: there is no `e3 login`.
+- Sign in with `e3 auth login <server>`: there is no `e3 login`. A run is
+  `e3 dataflow run <repo> <ws>`: there is no `e3 start`.
+- A release or a sync runs nothing: run the dataflow after either.
+- A release is refused while its Files declarations read a source the target
+  hasn't bound: bind it in the target first.
 - `secrets set` reads the value from stdin unless `--value` is given; the
   next run reads the new value.
 - The version is the @elaraai lockstep: use the CLI of the release your

package/skills/e3-cloud-files/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: e3-cloud-files
+description: "Files for e3 cloud — a solution's inputs that come from files in a bucket (s3://bucket/prefix/), declared in its code and synced when asked, the same on a local repository and a deployed workspace. Use when: (1) Declaring which inputs a bucket's files fill with Files.source(name) and its file, latest, folder and listing, then Files.manifest([...]) as a module's default export, (2) Decoding what arrives in a task: a Blob (file, latest), a Dict of path to Blob (folder) or a listing of sizes, times and ETags, as East's JSON, CSV or text, (3) Deploying the declarations to a workspace and binding each source to s3://bucket/prefix/ with e3-cloud files deploy and bind, (4) Syncing what changed with e3-cloud files sync, locally with your own cloud profile (--profile, --latest), then running the dataflow with e3 dataflow run, (5) Reading a refusal: declarations that don't fit the package (FilesDeclarationError, a deploy's problems),… See the detailed scope below."
+---
+
+## Detailed skill scope
+
+Files for e3 cloud — a solution's inputs that come from files in a bucket (s3://bucket/prefix/), declared in its code and synced when asked, the same on a local repository and a deployed workspace. Use when: (1) Declaring which inputs a bucket's files fill with Files.source(name) and its file, latest, folder and listing, then Files.manifest([...]) as a module's default export, (2) Decoding what arrives in a task: a Blob (file, latest), a Dict of path to Blob (folder) or a listing of sizes, times and ETags, as East's JSON, CSV or text, (3) Deploying the declarations to a workspace and binding each source to s3://bucket/prefix/ with e3-cloud files deploy and bind, (4) Syncing what changed with e3-cloud files sync, locally with your own cloud profile (--profile, --latest), then running the dataflow with e3 dataflow run, (5) Reading a refusal: declarations that don't fit the package (FilesDeclarationError, a deploy's problems), an unbound source, a file over its limit, a protected workspace (workspace_protected), (6) Moving declarations to production through staging: a release carries them with the package and apps, a rollback restores them, a copy brings bindings and what each input took, and production's bindings stay its own, (7) Reading Files' East types (FilesManifestType, FilesBindingType, FilesSyncReportType — @elaraai/e3-cloud-types).
+
+# e3-cloud-files — files as e3 inputs
+
+A solution says in its code which of its inputs come from files in a bucket. Each
+workspace says where those files are, a bucket and a prefix, and
+`e3-cloud files sync` brings in what changed: on a local repository with your
+own cloud credentials, in the cloud with the platform's read-only role. A file
+arrives as it is, a `Blob`, and a task decodes it. Nothing polls: a sync runs
+when someone asks.
+
+Read `README.md` for the author's guide; this file is the short form.
+
+## Before writing code — search the example index
+
+Every e3 cloud API has an example in the plugin's index: the decoding
+functions of `@elaraai/e3-cloud-files`, and the hand-written entries for
+`Files.source`, its shapes, `Files.manifest` and the `e3-cloud files`
+commands. Before writing or changing Files code:
+
+1. Call `search_e3_cloud_examples` for the
+   part you are about to write. Summaries come back first: id, description
+   and keywords, a few hundred bytes each.
+2. Fetch the one or two that match with
+   `get_e3_cloud_example` and pattern your code
+   on them.
+3. For what a task does with the decoded data, search East's index too, with
+   the East plugin's `search_east_examples`.
+4. Do not read `node_modules/@elaraai/**` or `*.examples.ts` files
+   wholesale, and do not reason from `.d.ts` signatures: the index holds the
+   same code, exact and far cheaper.
+
+Nothing is injected for you; the search is the step.
+
+## Quick Start
+
+```ts
+// src/files.ts: which inputs the files fill
+import { Files } from '@elaraai/e3-cloud-files';
+export const upload = Files.source('upload');
+export const rates = upload.file('rates', { key: 'rates.json' });
+export default Files.manifest([upload]);
+
+// src/package.ts: a task decodes the file
+const decodeRates = East.function([BlobType], ArrayType(Rate), (_$, file) => file.decodeUtf8().parseJson(ArrayType(Rate)));
+export const rateTable = e3.task('rate_table', [rates], decodeRates, { runner });
+export default e3.package('orders', '1.0.0', rateTable);
+```
+
+```bash
+e3 workspace deploy ./repo dev --from-source src/package.ts
+e3-cloud files deploy ./repo dev src/files.ts                          # checked against the package dev runs
+e3-cloud files bind   ./repo dev upload s3://bucket/prefix/ --profile p # where upload's files are, for dev
+e3-cloud files sync   ./repo dev                                        # what changed comes in
+e3 dataflow run ./repo dev                                              # the dataflow runs on it
+```
+
+## Decision Tree
+
+```
+What do you need?
+├─ Declare which inputs a bucket's files fill (src/files.ts)
+│   ├─ A place files come from        → Files.source(name) — each workspace binds it to s3://bucket/prefix/
+│   ├─ One known file                 → source.file(input, { key })                    input: Blob
+│   ├─ The newest of a folder         → source.latest(input, { prefix, include? })     input: Blob, the greatest key
+│   ├─ Every file of a folder         → source.folder(input, { prefix, include? })     input: Dict<String, Blob> by path
+│   ├─ A folder's files, not bytes    → source.listing(input, { prefix, include? })    input: Dict<String, {size, modified, etag}>
+│   ├─ Subfolders' files too          → include: '**/*.csv' ('*.csv' is the top level only)
+│   └─ What deploy deploys            → export default Files.manifest([source, …])
+├─ Decode what arrives, in a task
+│   ├─ East's JSON                    → file.decodeUtf8().parseJson(T)
+│   ├─ CSV with a header              → file.decodeCsv(Row, { delimiter: ',' })
+│   ├─ Lines of text                  → file.decodeUtf8().split('\n')
+│   ├─ A folder's files as one array  → files.flattenToArray(($, file, path) => …)
+│   ├─ Some of a folder's files       → files.filter(($, file, path) => path.startsWith('2026/'))
+│   └─ Choose files by name or time   → a listing: rows.filter(($, row) => row.modified.greaterThan(since))
+├─ Bring the files into a workspace (the e3-cloud CLI; <repo> a local path or a repository URL)
+│   ├─ Deploy the declarations        → e3-cloud files deploy <repo> <ws> src/files.ts [--dry-run]
+│   ├─ Say where a source's files are → e3-cloud files bind <repo> <ws> <source> s3://bucket/prefix/ [--region r]
+│   │   └─ Locally only               → --profile <aws profile>, --latest <n> (each folder's n greatest keys)
+│   ├─ Bring in what changed          → e3-cloud files sync <repo> <ws> [--input name…] [--dry-run]
+│   ├─ What is declared, bound, synced → e3-cloud files status <repo> <ws>
+│   └─ Run the dataflow on it         → e3 dataflow run <repo> <ws> (a sync doesn't run it)
+├─ Production: a workspace with a staging (a deployed repository's URL)
+│   ├─ Change its declarations        → files deploy to the staging, then e3-cloud release <url> <staging> <production>
+│   ├─ A source it doesn't bind yet   → e3-cloud files bind <url> <production> <source> s3://… before the release
+│   ├─ See what a release does        → e3-cloud release … --plan (each input added, changed, unchanged, removed)
+│   ├─ After a release                → e3-cloud files sync <url> <production>, then e3 dataflow run
+│   ├─ Undo a release                 → e3-cloud rollback <url> <production> (declarations go back with the package)
+│   ├─ An emergency change            → e3-cloud files deploy … --force (an admin's; history records it; the next release undoes it)
+│   └─ Rehearse on production's files → e3-cloud staging add … (a copy: declarations, bindings, what each input took)
+├─ Keep synced inputs across a package deploy → e3 workspace deploy … --inputs keep-edited
+└─ Drive it from code
+    ├─ The checks                     → @elaraai/e3-cloud-files/check: checkFiles, checkBindings, readPackageInputs
+    ├─ The sync over your own ports   → @elaraai/e3-cloud-files/sync: syncFiles (FilesReader, FilesWriter, FilesLedger)
+    ├─ Writing an e3 store            → @elaraai/e3-cloud-files/storage: storageWriter(storage, repo, ws)
+    └─ Reading a bucket               → @elaraai/e3-cloud-files/s3: s3FilesReader(client, { bucket, prefix })
+```
+
+## Declare the files
+
+```ts
+// src/files.ts
+import { Files } from '@elaraai/e3-cloud-files';
+
+export const upload = Files.source('upload');   // each workspace binds it to a bucket and prefix
+
+export const rates  = upload.file('rates', { key: 'rates.json' });                         // input: Blob
+export const stock  = upload.latest('stock', { prefix: 'stock/', include: '*.json' });    // input: Blob, the greatest key
+export const orders = upload.folder('orders', { prefix: 'orders/', include: '*.json' });  // input: Dict<String, Blob>
+export const orderFiles = upload.listing('order_files', { prefix: 'orders/' });           // input: each file's size, modified, etag
+
+export default Files.manifest([upload]);       // what e3-cloud files deploy deploys
+```
+
+- Each shape is an ordinary `e3.input`, unassigned until a sync sets it: use
+  it in tasks as any input, and give the tasks to `e3.package` as usual.
+- Keys and prefixes are relative to where a workspace binds the source; a
+  prefix is `''` or ends with `/`.
+- `include` is a glob over the path under the prefix: `*` within one folder,
+  `**` across folders, `?` one character, `[a-z]` one of a set (`[!_]` any
+  but), `{csv,json}` any of its alternatives (`*.{csv,json}`).
+- `latest` takes the greatest key: name files so the newest sorts last
+  (`2026-10-02.json`).
+
+## Decode in a task
+
+```ts
+const decodeRates = East.function([BlobType], ArrayType(Rate), (_$, file) =>
+  file.decodeUtf8().parseJson(ArrayType(Rate)));
+const decodeOrders = East.function([FilesFolderType], ArrayType(Order), (_$, files) =>
+  files.flattenToArray((_$, file) => file.decodeUtf8().parseJson(ArrayType(Order))));
+
+export const rateTable = e3.task('rate_table', [rates], decodeRates, { runner });
+```
+
+CSV: `file.decodeCsv(Row, { delimiter: ',' })`. A folder is keyed by each
+file's path under the prefix, in path order.
+
+## Deploy, bind and sync
+
+```
+e3-cloud files deploy <repo> <workspace> src/files.ts [--dry-run]
+e3-cloud files bind   <repo> <workspace> upload s3://bucket/prefix/ [--region r] [--profile p] [--latest n]
+e3-cloud files sync   <repo> <workspace> [--input name...] [--dry-run]
+e3-cloud files status <repo> <workspace>
+e3 dataflow run <repo> <workspace>
+```
+
+`<repo>` is a local repository's path or a repository URL. Deploy the package
+first (`e3 workspace deploy`), then the declarations, which are checked
+against it. A sync reads only files whose ETag or size changed, writes only
+inputs whose files changed, and prints the next command when any did. It
+doesn't run the dataflow: `e3 dataflow run` does. Locally the bytes land only in the
+repository; `--profile` names the profile to read with and `--latest n`
+keeps only each folder's n greatest keys.
+
+## Traps
+
+- An input a mapping fills must be writable and of exactly its shape's type:
+  `Blob`, `Dict<String, Blob>` (`FilesFolderType`) or the listing's
+  (`FilesListingType`). Declare it through the shape; never write it with
+  `e3.input` yourself.
+- A file over 1 GiB less 64 KiB (`file`, `latest`), or over 64 MiB less
+  64 KiB in a folder, is refused and named in the report, never truncated.
+  So is a file the sync can't read (archived, under a key it may not use,
+  changed while it read it): the sync goes on, and the next tries it again.
+- Deploying a new package can make the declarations no longer fit: a sync then
+  refuses until they're deployed again. A package deploy also resets synced
+  inputs unless it keeps them (`--inputs keep-edited`); the next sync takes
+  them again whole.
+- A changed declaration, or a source bound elsewhere, has its inputs taken
+  again whole at the next sync.
+- A workspace with a staging refuses `files deploy` (`workspace_protected`):
+  deploy to the staging and release. A release is refused while the
+  declarations read a source the production workspace hasn't bound: bind it
+  there first. A release syncs nothing: sync production after it.
+- Bindings never travel with a release; a copy carries them. A staging
+  started as a copy of production reads production's files until you bind it
+  elsewhere.
+- The version is the @elaraai lockstep: use the same version as east and e3.
+
+## Related skills
+
+- **e3** — packages, tasks, inputs, the dataflow and the `e3` CLI.
+- **east** — the East language a task's decoding is written in.
+- **e3-cloud-cli** — the rest of the `e3-cloud` CLI: apps, staging, releases,
+  rollbacks, users, secrets and schedules, and the app lifecycle guides.