@foldspace_npm/harness 0.1.32 → 0.1.34

package/src/video/share.mjs

@@ -0,0 +1,284 @@
+// foldspace share - the bytes half of sharing a video by a Foldspace link.
+//
+// The CLI holds no Foldspace sign-in (the editor's MCP does), so sharing is
+// three steps the agent takes, only after the human said yes:
+//   1. `npx foldspace share inspect` - sizes and checks the MP4 and poster here
+//   2. MCP `create_video_share` - returns one-time signed upload targets
+//      (`upload_command`), then `npx foldspace share upload` sends the files
+//      straight to Foldspace's video storage with them
+//   3. MCP `publish_video_share` - the server checks the files and returns
+//      the public link
+// Nothing here talks to Foldspace except the upload targets the MCP issued,
+// and nothing prints them: a target is a bearer credential for one object.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** GCS requires every chunk but the last to be a multiple of 256 KiB. */
+export const CHUNK_UNIT_BYTES = 256 * 1024;
+export const DEFAULT_CHUNK_BYTES = 32 * CHUNK_UNIT_BYTES; // 8 MiB
+const MAX_ATTEMPTS_PER_CHUNK = 4;
+
+/**
+ * The only hosts an upload may go to: Google Cloud Storage, where Foldspace's video bucket is, and
+ * this machine for the local demo. A target anywhere else is refused, so a tampered or injected
+ * upload command cannot send the human's recording somewhere else.
+ */
+export function isAllowedUploadUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol === "https:" && url.hostname === "storage.googleapis.com") return true;
+  return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+}
+
+/** Mirrors the server's caps (share-service SHARE_MAX_*): checked here so a too-big file fails before any upload. */
+export const MAX_VIDEO_BYTES = 500 * 1024 * 1024;
+export const MAX_POSTER_BYTES = 5 * 1024 * 1024;
+
+export class ShareError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** The newest video/*.mp4 that `record` made, with its poster beside it. */
+export function defaultVideo(projectDir) {
+  const dir = path.join(projectDir, "video");
+  let names = [];
+  try {
+    names = fs.readdirSync(dir).filter((name) => name.endsWith(".mp4"));
+  } catch {
+    // no video folder
+  }
+  if (!names.length) {
+    throw new ShareError("NO_VIDEO", "No video/*.mp4 in this project. Make one with `npx foldspace record`, or pass the MP4's path.");
+  }
+  const newest = names
+    .map((name) => ({ name, mtime: fs.statSync(path.join(dir, name)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime)[0].name;
+  return path.join(dir, newest);
+}
+
+export function posterFor(videoPath) {
+  return videoPath.replace(/\.mp4$/i, ".jpg");
+}
+
+/**
+ * Sizes the two files and runs the same structural checks the server's publish
+ * check runs (MP4 with ftyp, moov before mdat; JPEG poster), so the agent hears
+ * "re-encode with faststart" before uploading 500 MB rather than after.
+ */
+export function inspectForShare({ videoPath, posterPath }) {
+  const video = statFile(videoPath, "NO_VIDEO", "video");
+  const poster = statFile(posterPath, "NO_POSTER", "poster");
+  if (video.bytes > MAX_VIDEO_BYTES) throw new ShareError("TOO_LARGE", `The video is ${mb(video.bytes)} MB; the limit is ${mb(MAX_VIDEO_BYTES)} MB.`);
+  if (poster.bytes > MAX_POSTER_BYTES) throw new ShareError("TOO_LARGE", `The poster is ${mb(poster.bytes)} MB; the limit is ${mb(MAX_POSTER_BYTES)} MB.`);
+
+  const head = readSlice(posterPath, 0, 3);
+  if (!(head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff)) {
+    throw new ShareError("NOT_JPEG", "The poster must be a JPEG image.");
+  }
+  const durationS = readMp4Duration(videoPath, video.bytes);
+  return { video: { ...video, durationS }, poster };
+}
+
+/** Walks top-level boxes: ftyp first, moov before mdat; returns mvhd duration in seconds. */
+function readMp4Duration(file, size) {
+  const first = boxAt(file, 0, size);
+  if (!first || first.type !== "ftyp") throw new ShareError("NOT_MP4", "The video is not an MP4 file.");
+  let offset = first.size;
+  for (let i = 0; i < 64 && offset < size; i++) {
+    const box = boxAt(file, offset, size);
+    if (!box) throw new ShareError("NOT_MP4", "The MP4 is truncated or damaged.");
+    if (box.type === "mdat") {
+      throw new ShareError("NOT_FAST_START", "The MP4 is not fast-start (its moov box comes after the video data). Re-encode it with `-movflags +faststart`.");
+    }
+    if (box.type === "moov") {
+      const body = readSlice(file, offset + box.header, Math.min(box.size - box.header, 16 * 1024 * 1024));
+      return mvhdDurationSeconds(body);
+    }
+    offset += box.size;
+  }
+  throw new ShareError("NOT_MP4", "The MP4 has no moov box.");
+}
+
+function mvhdDurationSeconds(moov) {
+  let offset = 0;
+  while (offset + 8 <= moov.length) {
+    const size = moov.readUInt32BE(offset);
+    const type = moov.toString("latin1", offset + 4, offset + 8);
+    if (size < 8) break;
+    if (type === "mvhd") {
+      const body = moov.subarray(offset + 8, offset + size);
+      if (body[0] === 1) return Number(body.readBigUInt64BE(24)) / body.readUInt32BE(20);
+      return body.readUInt32BE(16) / body.readUInt32BE(12);
+    }
+    offset += size;
+  }
+  throw new ShareError("NOT_MP4", "The MP4 has no movie header.");
+}
+
+function boxAt(file, offset, fileSize) {
+  if (offset + 8 > fileSize) return null;
+  const head = readSlice(file, offset, 16);
+  let size = head.readUInt32BE(0);
+  let header = 8;
+  if (size === 1) {
+    size = Number(head.readBigUInt64BE(8));
+    header = 16;
+  } else if (size === 0) {
+    size = fileSize - offset;
+  }
+  if (size < header || offset + size > fileSize) return null;
+  return { type: head.toString("latin1", 4, 8), size, header };
+}
+
+/**
+ * Parses the `--targets` JSON that `create_video_share` put in the upload
+ * command: { video: {url, method, headers}, poster: {...} }.
+ */
+export function parseTargets(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(text || ""));
+  } catch {
+    throw new ShareError("BAD_TARGETS", "--targets is not valid JSON. Copy the upload command from create_video_share exactly.");
+  }
+  for (const name of ["video", "poster"]) {
+    const target = parsed?.[name];
+    if (!target || typeof target.url !== "string" || target.method !== "POST" || typeof target.headers !== "object") {
+      throw new ShareError("BAD_TARGETS", `--targets has no valid ${name} target. Copy the upload command from create_video_share exactly.`);
+    }
+    if (!isAllowedUploadUrl(target.url)) {
+      throw new ShareError("BAD_TARGETS", `The ${name} upload target is not Foldspace's video storage (https://storage.googleapis.com). Use only the command create_video_share returned.`);
+    }
+  }
+  return parsed;
+}
+
+/**
+ * GCS resumable upload: POST the signed URL to start a session, then PUT the
+ * file in chunks with Content-Range. On a dropped connection it asks the
+ * session how much arrived (`bytes * /total`) and resumes from there.
+ * Errors name the HTTP status and GCS's error code, never the URL.
+ */
+export async function resumableUpload(target, filePath, { fetchImpl = fetch, chunkBytes = DEFAULT_CHUNK_BYTES, label = "file" } = {}) {
+  if (chunkBytes % CHUNK_UNIT_BYTES !== 0) throw new Error("chunkBytes must be a multiple of 256 KiB");
+  const total = fs.statSync(filePath).size;
+  if (total === 0) throw new ShareError("UPLOAD_FAILED", `The ${label} is empty.`);
+  // redirect: "manual" everywhere, never "error": GCS answers every unfinished chunk with 308 "Resume
+  // Incomplete", which fetch would turn into a network error. A 3xx that names a Location is a real
+  // redirect, and is refused (rejectRedirect): storage never sends an upload somewhere else.
+  const start = rejectRedirect(await fetchImpl(target.url, { method: "POST", headers: target.headers, body: "", redirect: "manual" }), label);
+  if (start.status !== 200 && start.status !== 201) {
+    throw new ShareError("UPLOAD_REFUSED", `Starting the ${label} upload failed: ${await describe(start)}. The upload targets last 30 minutes; if they expired, call create_video_share again.`);
+  }
+  const session = start.headers.get("location");
+  if (!session || !isAllowedUploadUrl(session)) throw new ShareError("UPLOAD_REFUSED", `Starting the ${label} upload returned no usable session.`);
+
+  let offset = 0;
+  let attempts = 0;
+  const handle = fs.openSync(filePath, "r");
+  const buffer = Buffer.alloc(Math.min(chunkBytes, total)); // one buffer, reused for every chunk
+  try {
+    while (offset < total) {
+      const end = Math.min(offset + chunkBytes, total) - 1;
+      const length = end - offset + 1;
+      fs.readSync(handle, buffer, 0, length, offset);
+      const chunk = buffer.subarray(0, length);
+      let response;
+      try {
+        response = await fetchImpl(session, {
+          method: "PUT",
+          headers: { "content-range": `bytes ${offset}-${end}/${total}` },
+          body: chunk,
+          redirect: "manual",
+        });
+      } catch (error) {
+        if (++attempts >= MAX_ATTEMPTS_PER_CHUNK) throw new ShareError("UPLOAD_FAILED", `The ${label} upload kept failing: ${error.message}`);
+        offset = await committedBytes(fetchImpl, session, total);
+        continue;
+      }
+      rejectRedirect(response, label);
+      if (response.status === 200 || response.status === 201) return { bytes: total };
+      if (response.status === 308) {
+        // Progress resets the retry count; a 308 whose committed range did not move counts as a failed
+        // attempt, so a session that never advances ends instead of looping forever.
+        const next = rangeEnd(response.headers.get("range"));
+        if (next > offset) attempts = 0;
+        else if (++attempts >= MAX_ATTEMPTS_PER_CHUNK) throw new ShareError("UPLOAD_FAILED", `The ${label} upload stopped moving: storage kept the same ${next} bytes.`);
+        offset = next;
+        continue;
+      }
+      if (response.status >= 500 && ++attempts < MAX_ATTEMPTS_PER_CHUNK) {
+        offset = await committedBytes(fetchImpl, session, total);
+        continue;
+      }
+      throw new ShareError("UPLOAD_FAILED", `The ${label} upload failed: ${await describe(response)}.`);
+    }
+  } finally {
+    fs.closeSync(handle);
+  }
+  throw new ShareError("UPLOAD_FAILED", `The ${label} upload did not finish.`);
+}
+
+async function committedBytes(fetchImpl, session, total) {
+  const status = rejectRedirect(await fetchImpl(session, { method: "PUT", headers: { "content-range": `bytes */${total}` }, body: "", redirect: "manual" }), "file");
+  if (status.status === 200 || status.status === 201) return total;
+  return rangeEnd(status.headers.get("range"));
+}
+
+/** A 3xx with a Location is a redirect away from storage: refused. (GCS's 308 Resume Incomplete has none.) */
+function rejectRedirect(response, label) {
+  if (response.status >= 300 && response.status < 400 && response.headers.get("location")) {
+    throw new ShareError("UPLOAD_REFUSED", `The ${label} upload was redirected; uploads go only to Foldspace's video storage.`);
+  }
+  return response;
+}
+
+/** "bytes=0-1048575" → 1048576 (the next byte to send); no header → 0. */
+function rangeEnd(header) {
+  const match = /bytes=0-(\d+)/.exec(header || "");
+  return match ? Number(match[1]) + 1 : 0;
+}
+
+async function describe(response) {
+  let code = "";
+  try {
+    const text = await response.text();
+    code = /<Code>([^<]{1,64})<\/Code>/.exec(text)?.[1] ?? "";
+  } catch {
+    // no body
+  }
+  return `HTTP ${response.status}${code ? ` ${code}` : ""}`;
+}
+
+function statFile(file, code, label) {
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile()) throw new Error("not a file");
+    return { path: file, bytes: stat.size };
+  } catch {
+    throw new ShareError(code, `No ${label} at ${file}.`);
+  }
+}
+
+function readSlice(file, offset, length) {
+  const handle = fs.openSync(file, "r");
+  try {
+    const buffer = Buffer.alloc(length);
+    const read = fs.readSync(handle, buffer, 0, length, offset);
+    return buffer.subarray(0, read);
+  } finally {
+    fs.closeSync(handle);
+  }
+}
+
+function mb(bytes) {
+  return Math.round(bytes / (1024 * 1024));
+}

package/templates/agent-starter/agent/constants.ts

@@ -2,9 +2,23 @@ export const AGENT_API_NAME = {{AGENT_API_NAME_JSON}};
 export const PRODUCT_ID = {{PRODUCT_ID_JSON}};
 export const APP_DOMAIN = {{APP_DOMAIN_JSON}};
 
+/**
+ * Whether each of the product's customers has their own subdomain
+ * (acme.example.com, globex.example.com). Left undecided until the human has
+ * answered: `true` or `false` is their answer, never a guess.
+ */
+export const PER_CUSTOMER_SUBDOMAIN: boolean | undefined = undefined;
+
 /**
  * Empty until you capture the app's own XHR. A guessed host looks like it
- * worked. Include an explicit port if the app uses one.
+ * worked. One of:
+ * - `"https://api.example.com"` - every customer calls the same backend.
+ *   Include an explicit port if the app uses one.
+ * - `"/api"` - the backend is on the page's own host.
+ * - `"https://{subdomain}.api.example.com"` - each customer's backend carries
+ *   their subdomain; the runtime puts each user's own in.
+ * With `PER_CUSTOMER_SUBDOMAIN = true`, never the address you observed as it
+ * is: that is one customer's backend, and every user's agent would call it.
  */
 export const API_BASE = "";
 

package/templates/agent-starter/agent/utils.ts

@@ -14,6 +14,9 @@
  * - `apiFetch` - JSON + `Authorization: Bearer`. For any other sign-in, see
  *   "Custom auth" below.
  * - `apiFetchBinary` — same auth, raw bytes (file download).
+ * - `apiBaseUrl` — `API_BASE` for this page: `"/api"` on the page's own host,
+ *   `{subdomain}` filled with this user's own. A custom `apiFetch` builds its
+ *   URLs from it, never from `API_BASE` directly.
  * - `publicFetch` — no token; marketing / public origin only.
  * - `getAuthToken` / `parseJwt` / `redact` — session read and safe logging.
  * - `mapWithConcurrency` — cap parallel fetches over a list.

package/templates/agent-starter/claude-settings.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Written by foldspace init: the commands a build runs, allowed up front so the coding agent is not stopped one denial at a time. init and upgrade are left out on purpose, so they ask, like anything not listed. foldspace deploy is Foldspace-internal and never runs in a build.",
+  "$comment": "Written by foldspace init: the commands a build runs, allowed up front so the coding agent is not stopped one denial at a time. init and upgrade are left out on purpose, so they ask, like anything not listed; so is share upload, which sends a video out. foldspace deploy is Foldspace-internal and never runs in a build.",
   "permissions": {
     "allow": [
       "Bash(npx foldspace help:*)",
@@ -12,6 +12,8 @@
       "Bash(npx foldspace badge:*)",
       "Bash(npx foldspace published:*)",
       "Bash(npx foldspace record:*)",
+      "Bash(npx foldspace share inspect:*)",
+      "Bash(npx foldspace sync:*)",
       "Bash(npm install:*)",
       "Bash(npm run build:*)",
       "Bash(npm run typecheck:*)",

package/templates/agent-starter/skills/review-experience/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: review-experience
+description: Check an experience's code before every save of the agent's code - it returns only the data the answer needs, every write waits for the user's yes, and it reaches nothing the user cannot reach in the product. A serious finding stops the save. Use before each repo_write of agent code, after `npx foldspace build` passed - not for a save that only brings agent/runtime/ up to date.
+---
+
+# Review an experience before it is saved
+
+Saving puts the code where it can be published for every user of the
+product - each with their own data, their own role and their own sign-in.
+What was right for the builder's account in the test window has to be
+right for all of them. This review is the last look before that.
+
+`npx foldspace build` already checked what can be read off the code: one
+customer's address written in, the user's token leaving the page,
+secrets, calls to hosts the project does not name. Those are not repeated
+here, and cards may draw any markup they need. This review is the three things only
+someone who knows what the experience is for can judge.
+
+## When
+
+Before **every** save of agent code with `repo_write` - the first one and
+each one after. Run it on the experiences the save changes; a save of only
+the files a build put in `agent/runtime/` needs no review.
+
+Build first: a save waits for `npx foldspace build` with no errors, then
+this review.
+
+## 1. Least data
+
+What `execute` returns reaches the agent and the model, and for a view card
+it is what the agent answers from (rule 2 of the manual). Return the facts
+the answer needs, picked one field at a time - nothing else.
+
+Read each `execute` and each card `callback` and check:
+
+- **Fields are picked by name.** Never `res.data`, a whole record, or
+  `...record` from the API.
+  *"Which invoices are due?"* needs invoice number, amount, due date and
+  status - not the customer record they came with (address, phone, tax id,
+  notes, the account manager).
+- **Only the ids the card or the next action uses.** An internal id nothing
+  reads is data for nothing.
+- **Other people's details only when the question is about them.** A list of
+  deals needs the deal owner's name, not their email and phone.
+- **Rows the card shows, not the whole table.** Cap the list at what the card
+  draws (and say how many there are in all, if the answer needs it).
+
+**Serious:** a whole record or the raw response returned; personal details
+(email, phone, address, date of birth, payment details, government ids) the
+answer does not need. **Fix now, not serious:** an extra harmless field.
+
+## 2. A yes before every write
+
+The agent acts with the user's own sign-in: a write is the user writing.
+It happens only after the user said yes to exactly that change.
+
+Find every write in the experience: an `apiFetch` (or `fetch`) with
+`method` `POST`, `PUT`, `PATCH` or `DELETE`, a form post (`submitForm`), and
+any helper in `agent/api/` that calls one. For each:
+
+Every write gets the user's yes in one of two ways:
+
+- **A card (visual widget), on the user's press.** The card shows what will
+  change before they press - `recipes/create-a-record` has the shape.
+  *Cancel the Pro plan* is a card that says *"Cancel your Pro plan on 1
+  November? You keep it until then."* with **Cancel plan** and **Keep it**;
+  nothing is sent until **Cancel plan** is pressed, and **Keep it** or closing
+  the card writes nothing.
+- **Text only (no card): the action is marked confirmation required.** Set
+  `confirmation_required: true` and a short `confirmation_message` on the
+  action (the Foldspace action tools take both; in Agent Studio it is the
+  action's *confirmation required* setting). Foldspace then asks the user
+  before `execute` runs.
+
+- **It writes what the user saw** - the same record, the same values - and
+  nothing besides: no "mark as read", no second record on the side.
+- **It is never repeated by itself.** A write that timed out may have landed:
+  say so, as `recipes/update-meeting-notes` does, rather than sending it again.
+
+⚠️ One case may need neither - this is a reading of
+`recipes/update-meeting-notes`, not yet a confirmed rule: **adding one new
+thing whose words the user gave in the same message** (*"add this to the
+meeting notes: ..."*). Their message is the yes, as long as `execute` writes
+exactly what they said and returns what was written. When in doubt, a card or confirmation required.
+
+**Serious:** a write with neither a card nor confirmation required that removes, cancels, replaces or
+overwrites something; sends something to someone (an email, an invite, a
+message); spends or refunds money or changes a plan; changes who can see or
+do what; or touches more than one record. A write the user did not ask for.
+
+## 3. Nothing the user cannot reach in the product
+
+The experience may reach only what this user could reach in the product
+itself. The builder is often signed in as an owner or an admin; most users
+are not.
+
+- **Every call is one the product's own screens make**, seen with
+  `npx foldspace observe screen` on a screen `observe menu` lists - not a path
+  found in the app's code, in its API docs, guessed, or reached by typing an
+  address. `docs/app-profile.md` says how each endpoint was established.
+- **A screen only an admin sees stays an admin's.** When the builder's
+  account can see admin screens (Users, Billing, Settings for the whole
+  account, anything under `/admin`), ask the human once, as a choice:
+  *"Do all your users see <the screen>, or only admins?"* Only admins: this
+  experience is not for everyone - say so, and do not save it as one.
+- **Nothing widens the reach.** No `all=true`, `scope=account`,
+  `includeDeleted`, export-everything or impersonation calls. A user's,
+  team's or account's id comes from the session (`/me`,
+  `recipes/who-is-the-user`) or from an earlier action's result - never from
+  the user's or the model's words.
+- **Do not rely on the screen being hidden.** Some products hide a screen and
+  still answer its call for anyone signed in. The test is what the product
+  shows this kind of user, not what its backend lets through.
+
+**Serious:** a call to an endpoint no screen for this kind of user makes; an
+admin-only screen in an experience for everyone; an id that widens the reach
+taken from words.
+
+## 4. What happens next
+
+- **Nothing serious:** save. In chat, one line at most - *"Checked it before
+  saving."* Fix the not-serious ones in the same pass, before the save.
+- **Something serious:** do not save. It is your code: fix it - pick the
+  fields, move the write behind a card, drop the call - build again, and run
+  this review again. Then save.
+- **A serious finding only the human can settle** (whether regular users see
+  a screen, whether a write needs a card): ask as a choice, with the safe
+  option first, and save only after the answer settles it. Their answer goes
+  in `docs/app-profile.md`, with the date.
+- **Never save around it** - not "for now", not to dev only: dev is where their
+  users can be sent next.
+
+Nothing here is said to the human in these words: in chat it is *"it only
+shows the invoice details, not the whole customer record"*, *"cancelling
+asks the user first"* - what their users will see.

package/templates/agent-starter/skills/share-a-video/SKILL.md

@@ -22,7 +22,8 @@ nothing to set.
 
 - **Real data from their account.** The signed-in app as it is: their records,
   their numbers, their name wherever the app or the panel shows it. Nothing is
-  blurred, nothing is made up, nothing is uploaded.
+  blurred, nothing is made up, and nothing is uploaded unless the human asks
+  for a share link (step 7).
 - **Sharing it is their call** - whether, and where. Like a screen recording
   they made themselves.
 - Never create demo data for the video, never blur or crop parts of it, and
@@ -181,7 +182,9 @@ If `ok` is false, find its `code` in the table below. If true, read the poster
 ended: each answer complete, none an error or "that action isn't available",
 and each one shows what its capabilities and line say. A bad one: offer
 another question for that use case, prove it, record again. If there is a
-`note` that it ran long, offer to drop the last scene.
+`note` that it ran long, offer to drop the last scene. If there is a
+`wideWindow` note, tell the human in one line and offer a narrower test window
+and a new recording; they decide.
 
 ## 6. Hand it over
 
@@ -199,8 +202,48 @@ another question for that use case, prove it, record again. If there is a
   goes is their call.
 
 **Sharing:** upload the MP4 itself to LinkedIn or X - that is also how it
-plays inline in the feed. A Foldspace share link (a page anyone can open to
-watch it) is coming; until then, the file.
+plays inline in the feed. Or a Foldspace share link (step 7): a page anyone
+with the link can open to watch it, with a "Build yours" button, and an email
+to them when it is watched.
+
+## 7. A Foldspace share link - only when they ask for one
+
+Offer it as one option next to "send me the file", never as the default.
+The link is public: anyone who has it can watch, with no sign-in. So before
+anything leaves this computer, ask once, as a choice: *"A share link is public
+to anyone who has it, and the video shows [what is on screen]. Create one?"*
+Only on a yes:
+
+1. `npx foldspace share inspect` (the newest `video/*.mp4` and its poster, or
+   pass the path). It uploads nothing. If it says the MP4 is not fast-start,
+   that file did not come from `record`: say so and stop.
+2. The Foldspace tool `create_video_share` with a title in their words (the
+   product and what the agent does, up to 200 characters), and `video_bytes`
+   and `poster_bytes` from step 1.
+3. Run the upload command it returns, exactly - it carries one-time upload
+   targets for 30 minutes. Pass `upload` the same video path and `--poster`
+   you gave `inspect`, if any, so it uploads the files `inspect` sized. Never
+   paste the targets into chat, a file or a commit. In Codex (or any editor
+   that runs commands in a sandbox), this command needs the network: run it
+   outside the sandbox through the editor's own approval, with one plain line
+   on why.
+4. When it prints `"status": "uploaded"`, the tool `publish_video_share` with
+   the `share_id`. It returns the link: give it to them as it is.
+5. Tell them in one line that they get an email at the first view and a daily
+   summary on days it is watched, and that you can show the numbers
+   (`get_video_share_stats`) or delete the link (`delete_video_share`) whenever
+   they ask. `publish_video_share` says whether those emails are on for this
+   share.
+6. They want the emails off, or back on: the tool
+   `set_video_share_notifications` with the `share_id` and
+   `email_notifications` (`false` stops them, `true` turns them on). It covers
+   that one video only.
+
+The tools refuse with a reason you pass on as it is: an EU account (share
+links are not offered there yet - send the file instead), a cap (shares per
+day, or a trial's monthly limit), or a sign-in by API key rather than as a
+person. The CLI never signs in to Foldspace and never reaches the Foldspace
+tools itself: steps 2 and 4 are tool calls you make.
 
 The video holds real data, so it is never saved with the code: `record` writes
 `video/.gitignore` (`*.mp4`, `*.jpg`) in every project. `video/scenes.json`