aethel 0.3.8 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.0.0 (2026-04-06)
+
+- release: 1.0.0
+
+## 0.4.0 (2026-04-06)
+
+- Add pull --all for full remote download
+
 ## 0.3.8 (2026-04-06)
 
 - Fix Drive upload checksum test stub

package/README.md

@@ -9,8 +9,6 @@
 
 Aethel brings a `snapshot → diff → stage → commit` workflow to Google Drive. Track changes on both sides, resolve conflicts explicitly, and keep a full sync history — all without leaving the command line. It also ships with a dual-pane TUI for hands-on file management.
 
----
-
 ## Install
 
 ```bash
@@ -33,6 +31,8 @@ npm run install:cli   # symlinks `aethel` into ~/.local/bin
 
 ## Setup
 
+![Aethel setup flow](docs/setup.gif)
+
 ### 1. Get Google OAuth Credentials
 
 1. Go to [Google Cloud Console](https://console.cloud.google.com/)
@@ -62,15 +62,20 @@ aethel auth                    # opens browser, saves token.json
 
 ### 4. Initialize a Workspace
 
+![Aethel init flow](docs/init.gif)
+
 ```bash
 aethel init --local-path ./my-drive     # sync entire My Drive
 aethel init --local-path ./workspace --drive-folder <folder-id>  # sync specific folder
+aethel pull --all -m "initial pull"     # hydrate local files from the current remote tree
 ```
 
 > `credentials.json` and `token.json` are local secrets — never commit them.
 
 ## Usage
 
+![Aethel usage flow](docs/usage.gif)
+
 ```bash
 aethel status                  # local vs remote changes at a glance
 aethel diff --side all         # detailed file-level diff
@@ -78,9 +83,12 @@ aethel add --all               # stage default suggested actions
 aethel commit -m "sync"        # execute staged operations
 
 aethel pull -m "pull"          # fetch remote changes and apply
+aethel pull --all              # download the full remote tree to local
 aethel push -m "push"          # push local changes to Drive
 ```
 
+`pull` applies remote changes relative to the latest snapshot. Use `pull --all` for the first full download or to rehydrate a local workspace from the current remote tree.
+
 ### Conflict Resolution
 
 When both local and remote change the same path:
@@ -104,28 +112,28 @@ Processes deepest-first for single-pass convergence, caches child state to minim
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `auth` | OAuth flow — creates `token.json`, verifies Drive access |
-| `init` | Initialize a local sync workspace |
-| `status` | Show local vs remote changes |
-| `diff` | Detailed file differences |
-| `add` | Stage changes |
-| `reset` | Unstage changes |
-| `commit` | Execute staged sync operations |
-| `pull` | Fetch and apply remote changes |
-| `push` | Push local changes to Drive |
-| `log` | Sync history |
-| `fetch` | Refresh remote state without applying |
-| `resolve` | Resolve conflicts (local / remote / both) |
-| `ignore` | Manage `.aethelignore` patterns |
-| `show` | Inspect a saved snapshot |
-| `restore` | Restore files from the last snapshot |
-| `rm` | Remove local files and stage remote deletion |
-| `mv` | Move or rename local files |
-| `clean` | List and optionally trash/delete Drive files |
-| `dedupe-folders` | Detect and merge duplicate remote folders |
-| `tui` | Launch interactive terminal UI |
+| Command            | Description                                                         |
+| ------------------ | ------------------------------------------------------------------- |
+| `auth`           | OAuth flow — creates `token.json`, verifies Drive access         |
+| `init`           | Initialize a local sync workspace                                   |
+| `status`         | Show local vs remote changes                                        |
+| `diff`           | Detailed file differences                                           |
+| `add`            | Stage changes                                                       |
+| `reset`          | Unstage changes                                                     |
+| `commit`         | Execute staged sync operations                                      |
+| `pull`           | Fetch and apply remote changes (`--all` for full remote download) |
+| `push`           | Push local changes to Drive                                         |
+| `log`            | Sync history                                                        |
+| `fetch`          | Refresh remote state without applying                               |
+| `resolve`        | Resolve conflicts (local / remote / both)                           |
+| `ignore`         | Manage `.aethelignore` patterns                                   |
+| `show`           | Inspect a saved snapshot                                            |
+| `restore`        | Restore files from the last snapshot                                |
+| `rm`             | Remove local files and stage remote deletion                        |
+| `mv`             | Move or rename local files                                          |
+| `clean`          | List and optionally trash/delete Drive files                        |
+| `dedupe-folders` | Detect and merge duplicate remote folders                           |
+| `tui`            | Launch interactive terminal UI                                      |
 
 ## TUI
 
@@ -135,20 +143,20 @@ aethel tui
 
 Dual-pane file browser — local filesystem on the left, Google Drive on the right.
 
-| Key | Action |
-|-----|--------|
-| `Tab` | Switch panes |
-| `Left` / `Right` | Navigate up / into directories |
-| `u` | Upload selected local file or folder to Drive |
-| `s` | Batch sync local folder to current Drive directory |
-| `U` | Upload from a manually entered path |
-| `n` | Rename selected local item |
-| `x` | Delete selected local item |
-| `Space` | Toggle selection in Drive pane |
-| `t` / `d` | Trash / permanently delete selected Drive items |
-| `/` | Filter by name |
-| `f` | Open the commands page and choose a TUI action |
-| `:` | Run any Aethel CLI command inside the TUI |
+| Key                  | Action                                             |
+| -------------------- | -------------------------------------------------- |
+| `Tab`              | Switch panes                                       |
+| `Left` / `Right` | Navigate up / into directories                     |
+| `u`                | Upload selected local file or folder to Drive      |
+| `s`                | Batch sync local folder to current Drive directory |
+| `U`                | Upload from a manually entered path                |
+| `n`                | Rename selected local item                         |
+| `x`                | Delete selected local item                         |
+| `Space`            | Toggle selection in Drive pane                     |
+| `t` / `d`        | Trash / permanently delete selected Drive items    |
+| `/`                | Filter by name                                     |
+| `f`                | Open the commands page and choose a TUI action     |
+| `:`                | Run any Aethel CLI command inside the TUI          |
 
 ## Ignore Patterns
 
@@ -165,11 +173,11 @@ build/
 
 ## Environment Variables
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `GOOGLE_DRIVE_CREDENTIALS_PATH` | `~/.config/aethel/credentials.json` | Path to OAuth credentials |
-| `GOOGLE_DRIVE_TOKEN_PATH` | `~/.config/aethel/token.json` | Path to cached OAuth token |
-| `AETHEL_DRIVE_CONCURRENCY` | `40` | Max concurrent Drive API requests |
+| Variable                          | Default                               | Description                       |
+| --------------------------------- | ------------------------------------- | --------------------------------- |
+| `GOOGLE_DRIVE_CREDENTIALS_PATH` | `~/.config/aethel/credentials.json` | Path to OAuth credentials         |
+| `GOOGLE_DRIVE_TOKEN_PATH`       | `~/.config/aethel/token.json`       | Path to cached OAuth token        |
+| `AETHEL_DRIVE_CONCURRENCY`      | `40`                                | Max concurrent Drive API requests |
 
 ## Architecture
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aethel",
-  "version": "0.3.8",
+  "version": "1.0.0",
   "description": "Git-style Google Drive sync CLI with interactive TUI",
   "type": "module",
   "license": "MIT",
@@ -26,6 +26,11 @@
   },
   "files": [
     "src/",
+    "scripts/demo.js",
+    "scripts/render-demo-gif.py",
+    "scripts/render-demo-screenshot.js",
+    "docs/demo.gif",
+    "docs/demo-screenshot.svg",
     "LICENSE",
     "README.md",
     "CHANGELOG.md",
@@ -33,6 +38,12 @@
     ".env.example"
   ],
   "scripts": {
+    "demo": "node scripts/demo.js",
+    "demo:gif": "python3 scripts/render-demo-gif.py",
+    "demo:screenshot": "node scripts/render-demo-screenshot.js",
+    "demo:setup": "python3 scripts/generate-cast.py && agg docs/setup.cast docs/setup.gif --font-size 32 --theme dracula",
+    "demo:init": "python3 scripts/generate-init-cast.py && agg docs/init.cast docs/init.gif --font-size 32 --theme dracula",
+    "demo:usage": "python3 scripts/generate-usage-cast.py && agg docs/usage.cast docs/usage.gif --font-size 32 --theme dracula",
     "start": "node src/cli.js",
     "auth": "node src/cli.js auth",
     "clean": "node src/cli.js clean",

package/scripts/demo.js

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { initWorkspace } from "../src/core/config.js";
+import { ensureFolder, resetFolderLookupCache } from "../src/core/drive-api.js";
+import { Repository } from "../src/core/repository.js";
+
+const FOLDER_MIME = "application/vnd.google-apps.folder";
+
+function md5(buffer) {
+  return createHash("md5").update(buffer).digest("hex");
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function folder(id, name, parentId, createdTime) {
+  return {
+    id,
+    name,
+    mimeType: FOLDER_MIME,
+    parents: parentId ? [parentId] : [],
+    createdTime,
+    modifiedTime: createdTime,
+    md5Checksum: null,
+    size: null,
+    trashed: false,
+  };
+}
+
+function file(id, name, parentId, createdTime, content) {
+  const body = Buffer.from(content);
+  return {
+    id,
+    name,
+    mimeType: "application/octet-stream",
+    parents: [parentId],
+    createdTime,
+    modifiedTime: createdTime,
+    md5Checksum: md5(body),
+    size: body.length,
+    trashed: false,
+    body,
+  };
+}
+
+function createFakeDrive(initialItems = []) {
+  const items = new Map();
+  const contentById = new Map();
+  let sequence = 0;
+  let idCounter = 1000;
+
+  for (const item of initialItems) {
+    const next = clone(item);
+    delete next.body;
+    items.set(next.id, next);
+    if (item.body) {
+      contentById.set(next.id, Buffer.from(item.body));
+    }
+  }
+
+  function decodeQueryValue(value) {
+    return value.replace(/\\\\/g, "\\").replace(/\\'/g, "'");
+  }
+
+  function matches(item, query) {
+    if (!query) {
+      return true;
+    }
+
+    return query.split(" and ").every((part) => {
+      if (part === "trashed = false") {
+        return !item.trashed;
+      }
+
+      const nameMatch = part.match(/^name = '(.+)'$/);
+      if (nameMatch) {
+        return item.name === decodeQueryValue(nameMatch[1]);
+      }
+
+      const mimeMatch = part.match(/^mimeType = '(.+)'$/);
+      if (mimeMatch) {
+        return item.mimeType === decodeQueryValue(mimeMatch[1]);
+      }
+
+      const parentMatch = part.match(/^'(.+)' in parents$/);
+      if (parentMatch) {
+        return (item.parents || []).includes(parentMatch[1]);
+      }
+
+      return true;
+    });
+  }
+
+  async function drain(stream) {
+    if (!stream) {
+      return Buffer.alloc(0);
+    }
+
+    const chunks = [];
+    for await (const chunk of stream) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+  }
+
+  function touch(item) {
+    item.modifiedTime = new Date(1710000000000 + sequence++).toISOString();
+  }
+
+  return {
+    files: {
+      async list({ q, pageSize = 1000, pageToken, orderBy }) {
+        const matchesQuery = [...items.values()].filter((item) => matches(item, q));
+        matchesQuery.sort((left, right) => {
+          if (orderBy === "createdTime desc") {
+            return Date.parse(right.createdTime) - Date.parse(left.createdTime);
+          }
+          return String(left.id).localeCompare(String(right.id));
+        });
+
+        const start = Number(pageToken || 0);
+        const slice = matchesQuery.slice(start, start + pageSize).map(clone);
+        const nextPageToken =
+          start + pageSize < matchesQuery.length ? String(start + pageSize) : undefined;
+
+        return {
+          data: {
+            files: slice,
+            nextPageToken,
+          },
+        };
+      },
+      async create({ requestBody, media }) {
+        const body = await drain(media?.body);
+        const id = `id-${++idCounter}`;
+        const createdTime = new Date(1710000000000 + sequence++).toISOString();
+        const item = {
+          id,
+          name: requestBody.name,
+          mimeType: requestBody.mimeType || "application/octet-stream",
+          parents: requestBody.parents || [],
+          createdTime,
+          modifiedTime: createdTime,
+          md5Checksum: requestBody.mimeType === FOLDER_MIME ? null : md5(body),
+          size: requestBody.mimeType === FOLDER_MIME ? null : body.length,
+          trashed: false,
+        };
+        items.set(id, item);
+        if (item.mimeType !== FOLDER_MIME) {
+          contentById.set(id, body);
+        }
+        return { data: clone(item) };
+      },
+      async update({ fileId, requestBody = {}, addParents, removeParents, media }) {
+        const body = await drain(media?.body);
+        const item = items.get(fileId);
+
+        if (!item) {
+          throw new Error(`Missing file: ${fileId}`);
+        }
+
+        if (requestBody.name) {
+          item.name = requestBody.name;
+        }
+
+        if (Object.hasOwn(requestBody, "trashed")) {
+          item.trashed = Boolean(requestBody.trashed);
+        }
+
+        if (addParents || removeParents) {
+          const nextParents = new Set(item.parents || []);
+          for (const parentId of String(removeParents || "").split(",").filter(Boolean)) {
+            nextParents.delete(parentId);
+          }
+          if (addParents) {
+            nextParents.add(addParents);
+          }
+          item.parents = [...nextParents];
+        }
+
+        if (body.length && item.mimeType !== FOLDER_MIME) {
+          item.md5Checksum = md5(body);
+          item.size = body.length;
+          contentById.set(fileId, body);
+        }
+
+        touch(item);
+        return { data: clone(item) };
+      },
+      async delete({ fileId }) {
+        items.delete(fileId);
+        contentById.delete(fileId);
+        return { data: {} };
+      },
+      async get({ fileId, alt }) {
+        if (fileId === "root") {
+          return {
+            data: {
+              id: "root",
+              name: "My Drive",
+              mimeType: FOLDER_MIME,
+              parents: [],
+              createdTime: "2026-01-01T00:00:00.000Z",
+            },
+          };
+        }
+
+        const item = items.get(fileId);
+        if (!item) {
+          throw new Error(`Missing file: ${fileId}`);
+        }
+
+        if (alt === "media") {
+          return {
+            data: Readable.from([contentById.get(fileId) || Buffer.alloc(0)]),
+          };
+        }
+
+        return { data: clone(item) };
+      },
+    },
+  };
+}
+
+function writeLocal(root, relativePath, content) {
+  const absolutePath = path.join(root, relativePath);
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  fs.writeFileSync(absolutePath, content);
+}
+
+function formatStatus(diff, staged) {
+  const lines = [];
+
+  if (diff.isClean && staged.length === 0) {
+    lines.push("Everything up to date.");
+    return lines;
+  }
+
+  if (staged.length) {
+    lines.push(`Staged changes (${staged.length}):`);
+    for (const entry of staged) {
+      lines.push(`  ${entry.action.padStart(15, " ")}  ${entry.path}`);
+    }
+  }
+
+  const stagedPaths = new Set(staged.map((e) => e.path));
+  const unstagedRemote = diff.remoteChanges.filter((c) => !stagedPaths.has(c.path));
+  const unstagedLocal = diff.localChanges.filter((c) => !stagedPaths.has(c.path));
+  const unstagedConflicts = diff.conflicts.filter((c) => !stagedPaths.has(c.path));
+
+  if (unstagedRemote.length) {
+    lines.push(`Remote changes (${unstagedRemote.length}):`);
+    for (const change of unstagedRemote) {
+      lines.push(`  ${change.shortStatus} ${change.path}  (${change.description})`);
+    }
+  }
+
+  if (unstagedLocal.length) {
+    lines.push(`Local changes (${unstagedLocal.length}):`);
+    for (const change of unstagedLocal) {
+      lines.push(`  ${change.shortStatus} ${change.path}  (${change.description})`);
+    }
+  }
+
+  if (unstagedConflicts.length) {
+    lines.push(`Conflicts (${unstagedConflicts.length}):`);
+    for (const change of unstagedConflicts) {
+      lines.push(`  ${change.shortStatus} ${change.path}  (${change.description})`);
+    }
+  }
+
+  return lines;
+}
+
+function formatDiff(diff) {
+  if (diff.isClean) {
+    return ["No changes detected."];
+  }
+
+  const lines = [];
+  const sections = [
+    ["Remote changes", diff.remoteChanges],
+    ["Local changes", diff.localChanges],
+    ["Conflicts", diff.conflicts],
+  ];
+
+  for (const [title, changes] of sections) {
+    if (!changes.length) {
+      continue;
+    }
+
+    lines.push(`${title}:`);
+    for (const change of changes) {
+      lines.push(`  ${change.shortStatus} ${change.path}`);
+      lines.push(`       ${change.description}`);
+    }
+  }
+
+  return lines;
+}
+
+async function commit(repo, message, snapshotHint) {
+  const result = await repo.executeStaged();
+  await repo.saveSnapshot(message, snapshotHint);
+  return result.summary;
+}
+
+function renderCommand(lines, command, output) {
+  if (lines.length) {
+    lines.push("");
+  }
+
+  lines.push(`$ ${command}`);
+  lines.push(...output);
+}
+
+export async function generateDemoTranscript({ redactWorkspace = false } = {}) {
+  const workspace = fs.mkdtempSync(path.join(os.tmpdir(), "aethel-demo-"));
+  const visibleWorkspace = redactWorkspace ? "/tmp/aethel-demo-XXXXXX" : workspace;
+  resetFolderLookupCache();
+
+  try {
+    initWorkspace(workspace, "root", "My Drive");
+
+    const drive = createFakeDrive([
+      folder("fld-docs", "docs", "root", "2026-04-01T10:00:00.000Z"),
+      folder("fld-notes", "notes", "root", "2026-04-01T10:01:00.000Z"),
+      file("file-spec", "spec.txt", "fld-docs", "2026-04-01T10:02:00.000Z", "Spec v1\n"),
+      file("file-ideas", "ideas.txt", "fld-notes", "2026-04-01T10:03:00.000Z", "Idea v1\n"),
+    ]);
+
+    const repo = new Repository(workspace, { drive });
+
+    writeLocal(workspace, "docs/spec.txt", "Spec v1\n");
+    writeLocal(workspace, "notes/ideas.txt", "Idea v1\n");
+    await repo.saveSnapshot("initial sync");
+
+    await drive.files.update({
+      fileId: "file-spec",
+      media: { body: Readable.from(["Spec v2 from Drive\n"]) },
+    });
+    const designFolderId = await ensureFolder(drive, "design");
+    await drive.files.create({
+      requestBody: {
+        name: "roadmap.txt",
+        parents: [designFolderId],
+      },
+      media: { body: Readable.from(["Roadmap from Drive\n"]) },
+    });
+    writeLocal(workspace, "notes/ideas.txt", "Idea v2 from local\n");
+    writeLocal(workspace, "drafts/todo.txt", "Local draft\n");
+    repo.invalidateRemoteCache();
+
+    const lines = [
+      "Aethel demo",
+      `Workspace: ${visibleWorkspace}`,
+      "Backend: fake Google Drive",
+      "",
+      "Scenario:",
+      "  Drive changed docs/spec.txt and added design/roadmap.txt",
+      "  Local changed notes/ideas.txt and added drafts/todo.txt",
+    ];
+
+    let state = await repo.loadState({ useCache: false });
+
+    renderCommand(lines, "aethel status", formatStatus(state.diff, repo.getStagedEntries()));
+    renderCommand(lines, "aethel diff --side all", formatDiff(state.diff));
+
+    const stagedCount = repo.stageChanges(
+      state.diff.changes.filter((change) => change.suggestedAction !== "conflict")
+    );
+    renderCommand(lines, "aethel add --all", [`Staged ${stagedCount} change(s).`]);
+    renderCommand(lines, "aethel status", formatStatus(state.diff, repo.getStagedEntries()));
+
+    const summary = await commit(repo, "demo sync");
+    renderCommand(lines, 'aethel commit -m "demo sync"', [`Commit complete: ${summary}`]);
+
+    state = await repo.loadState({ useCache: false });
+    renderCommand(lines, "aethel status", formatStatus(state.diff, repo.getStagedEntries()));
+
+    lines.push("");
+    lines.push(`Inspect the demo workspace at: ${visibleWorkspace}`);
+
+    return { workspace, lines };
+  } finally {
+    resetFolderLookupCache();
+  }
+}
+
+export async function runDemo({ cleanup = false, redactWorkspace = false } = {}) {
+  const { workspace, lines } = await generateDemoTranscript({ redactWorkspace });
+  process.stdout.write(`${lines.join("\n")}\n`);
+
+  if (cleanup) {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+}
+
+const entryPath = fileURLToPath(import.meta.url);
+
+if (process.argv[1] && path.resolve(process.argv[1]) === entryPath) {
+  const cleanup = process.argv.includes("--cleanup");
+  const redactWorkspace = process.argv.includes("--redact-workspace");
+
+  runDemo({ cleanup, redactWorkspace }).catch((error) => {
+    console.error(error?.stack || String(error));
+    process.exitCode = 1;
+  });
+}

package/scripts/render-demo-gif.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+
+from pathlib import Path
+from subprocess import run
+from PIL import Image, ImageDraw, ImageFont
+
+ROOT = Path(__file__).resolve().parent.parent
+OUTPUT = ROOT / "docs" / "demo.gif"
+DISPLAY_WIDTH = 1320
+DISPLAY_MIN_HEIGHT = 760
+LINE_HEIGHT = 30
+SCALE = 2
+
+
+def load_lines():
+    result = run(
+        ["node", "scripts/demo.js", "--cleanup", "--redact-workspace"],
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout.rstrip("\n").splitlines()
+
+
+def load_font(size):
+    for candidate in [
+        "/System/Library/Fonts/Supplemental/Times New Roman.ttf",
+        "/System/Library/Fonts/Supplemental/Times New Roman Bold.ttf",
+    ]:
+        path = Path(candidate)
+        if path.exists():
+            return ImageFont.truetype(str(path), size)
+    return ImageFont.load_default()
+
+
+def load_title_font(size):
+    for candidate in [
+        "/System/Library/Fonts/Supplemental/Times New Roman Bold.ttf",
+        "/System/Library/Fonts/Supplemental/Times New Roman.ttf",
+    ]:
+        path = Path(candidate)
+        if path.exists():
+            return ImageFont.truetype(str(path), size)
+    return ImageFont.load_default()
+
+
+def build_frame(lines, font, title_font, visible):
+    shown = lines[:visible]
+    width = DISPLAY_WIDTH * SCALE
+    height = max(DISPLAY_MIN_HEIGHT, 180 + len(lines) * LINE_HEIGHT) * SCALE
+    image = Image.new("RGB", (width, height), "#0b1324")
+    draw = ImageDraw.Draw(image)
+    draw.rounded_rectangle((40, 40, width - 40, height - 40), 44, fill="#0a0f1a", outline="#243044", width=4)
+    draw.rounded_rectangle((40, 40, width - 40, 108), 44, fill="#10192a")
+    draw.ellipse((84, 62, 108, 86), fill="#fb7185")
+    draw.ellipse((124, 62, 148, 86), fill="#f59e0b")
+    draw.ellipse((164, 62, 188, 86), fill="#22c55e")
+    draw.text((236, 52), "Aethel demo", font=title_font, fill="#dbe4f0")
+    y = 176
+    for line in shown:
+        draw.text((104, y), line, font=font, fill="#dbe4f0")
+        y += LINE_HEIGHT * SCALE
+    if visible < len(lines):
+        draw.rounded_rectangle((104, y + 8, 134, y + 48), 6, fill="#38bdf8")
+    return image.resize((DISPLAY_WIDTH, height // SCALE), Image.Resampling.LANCZOS)
+
+
+def main():
+    lines = load_lines()
+    font = load_font(24 * SCALE)
+    title_font = load_title_font(22 * SCALE)
+    checkpoints = [3, 7, 13, 21, 27, len(lines)]
+    frames = [build_frame(lines, font, title_font, count) for count in checkpoints]
+    durations = [500, 600, 700, 800, 900, 1800]
+    OUTPUT.parent.mkdir(parents=True, exist_ok=True)
+    frames[0].save(
+        OUTPUT,
+        save_all=True,
+        append_images=frames[1:],
+        duration=durations,
+        loop=0,
+        optimize=False,
+        disposal=2,
+    )
+    print(OUTPUT)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/render-demo-screenshot.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { generateDemoTranscript } from "./demo.js";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const outputPath = path.join(root, "docs", "demo-screenshot.svg");
+
+function escapeXml(value) {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+const { workspace, lines } = await generateDemoTranscript({ redactWorkspace: true });
+
+try {
+  const longest = lines.reduce((max, line) => Math.max(max, line.length), 0);
+  const charWidth = 12.4;
+  const lineHeight = 32;
+  const width = Math.max(1120, Math.ceil(longest * charWidth) + 160);
+  const height = lines.length * lineHeight + 168;
+  const text = lines
+    .map(
+      (line, index) =>
+        `<text x="64" y="${100 + index * lineHeight}" xml:space="preserve">${escapeXml(line)}</text>`
+    )
+    .join("\n");
+
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-label="Aethel demo screenshot">
+<defs>
+<linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+<stop offset="0%" stop-color="#0b1324"/>
+<stop offset="55%" stop-color="#111827"/>
+<stop offset="100%" stop-color="#1f2937"/>
+</linearGradient>
+<linearGradient id="glow" x1="0" y1="0" x2="1" y2="0">
+<stop offset="0%" stop-color="#22c55e"/>
+<stop offset="50%" stop-color="#38bdf8"/>
+<stop offset="100%" stop-color="#f59e0b"/>
+</linearGradient>
+</defs>
+<rect width="${width}" height="${height}" rx="28" fill="url(#bg)"/>
+<rect x="24" y="24" width="${width - 48}" height="${height - 48}" rx="20" fill="#0a0f1a" stroke="#243044"/>
+<rect x="24" y="24" width="${width - 48}" height="36" rx="20" fill="#10192a"/>
+<circle cx="52" cy="42" r="7" fill="#fb7185"/>
+<circle cx="74" cy="42" r="7" fill="#f59e0b"/>
+<circle cx="96" cy="42" r="7" fill="#22c55e"/>
+<rect x="132" y="35" width="${Math.min(320, width - 220)}" height="12" rx="6" fill="url(#glow)" opacity="0.8"/>
+<g fill="#dbe4f0" font-family="'Times New Roman', Times, serif" font-size="22">
+${text}
+</g>
+</svg>
+`;
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, svg);
+  process.stdout.write(`${outputPath}\n`);
+} finally {
+  fs.rmSync(workspace, { recursive: true, force: true });
+}

package/src/cli.js

@@ -301,23 +301,28 @@ async function handleStatus(options) {
     }
   }
 
-  if (diff.remoteChanges.length) {
-    console.log(`\nRemote changes (${diff.remoteChanges.length}):`);
-    for (const change of diff.remoteChanges) {
+  const stagedPaths = new Set(staged.map((e) => e.path));
+  const unstagedRemote = diff.remoteChanges.filter((c) => !stagedPaths.has(c.path));
+  const unstagedLocal = diff.localChanges.filter((c) => !stagedPaths.has(c.path));
+  const unstagedConflicts = diff.conflicts.filter((c) => !stagedPaths.has(c.path));
+
+  if (unstagedRemote.length) {
+    console.log(`\nRemote changes (${unstagedRemote.length}):`);
+    for (const change of unstagedRemote) {
       console.log(`  ${change.shortStatus} ${change.path}  (${change.description})`);
     }
   }
 
-  if (diff.localChanges.length) {
-    console.log(`\nLocal changes (${diff.localChanges.length}):`);
-    for (const change of diff.localChanges) {
+  if (unstagedLocal.length) {
+    console.log(`\nLocal changes (${unstagedLocal.length}):`);
+    for (const change of unstagedLocal) {
       console.log(`  ${change.shortStatus} ${change.path}  (${change.description})`);
     }
   }
 
-  if (diff.conflicts.length) {
-    console.log(`\nConflicts (${diff.conflicts.length}):`);
-    for (const change of diff.conflicts) {
+  if (unstagedConflicts.length) {
+    console.log(`\nConflicts (${unstagedConflicts.length}):`);
+    for (const change of unstagedConflicts) {
       console.log(`  ${change.shortStatus} ${change.path}  (${change.description})`);
     }
   }
@@ -513,6 +518,37 @@ async function handlePull(paths, options) {
   const repo = await openRepo(options);
   const { diff, remoteState } = await loadStateWithProgress(repo, { useCache: false });
 
+  if (options.all) {
+    let remoteFiles = remoteState.files;
+
+    if (paths && paths.length > 0) {
+      remoteFiles = remoteFiles.filter((file) =>
+        paths.some((p) => matchesPattern(file.path, p))
+      );
+    }
+
+    if (!remoteFiles.length) {
+      console.log("No remote files matched.");
+      return;
+    }
+
+    if (options.dryRun) {
+      console.log(`Would pull ${remoteFiles.length} remote item(s):`);
+      for (const file of remoteFiles) {
+        console.log(`  +R ${file.path}  (full remote download)`);
+      }
+      return;
+    }
+
+    const count = repo.stageRemoteFilesForDownload(remoteFiles);
+    console.log(`Staged ${count} remote item(s). Committing...`);
+    await handleCommit({ ...options, message: options.message || "pull" }, {
+      repo,
+      snapshotHint: { remote: remoteState },
+    });
+    return;
+  }
+
   let remoteChanges = diff.changes.filter((change) =>
     [
       ChangeType.REMOTE_ADDED,
@@ -1100,6 +1136,7 @@ async function main() {
       .command("pull")
       .description("Download remote changes")
       .argument("[paths...]", "Specific paths to pull (default: all)")
+      .option("--all", "Download all remote files regardless of snapshot state")
       .option("-m, --message <message>", "Commit message")
       .option("--force", "Force-pull conflicts (remote wins)")
       .option("--dry-run", "Preview changes without applying")

package/src/core/repository.js

@@ -47,6 +47,7 @@ import {
   stageChange,
   stageChanges,
   stageConflictResolution,
+  stageRemoteFilesForDownload,
   stagedEntries,
   unstageAll,
   unstagePath,
@@ -190,6 +191,10 @@ export class Repository {
     return stageChanges(this._root, changes);
   }
 
+  stageRemoteFilesForDownload(remoteFiles) {
+    return stageRemoteFilesForDownload(this._root, remoteFiles);
+  }
+
   unstagePath(targetPath) {
     return unstagePath(this._root, targetPath);
   }

package/src/core/staging.js

@@ -50,6 +50,26 @@ export function stageChanges(root, changes) {
   return changes.length;
 }
 
+export function stageRemoteFilesForDownload(root, remoteFiles) {
+  const index = readIndex(root);
+  const byPath = new Map((index.staged || []).map((entry) => [entry.path, entry]));
+
+  for (const remoteFile of remoteFiles) {
+    byPath.set(remoteFile.path, {
+      action: "download",
+      path: remoteFile.path,
+      localPath: remoteFile.path,
+      fileId: remoteFile.id,
+      remotePath: remoteFile.path,
+      ...(remoteFile.isFolder ? { isFolder: true } : {}),
+    });
+  }
+
+  index.staged = [...byPath.values()];
+  writeIndex(root, index);
+  return remoteFiles.length;
+}
+
 export function unstagePath(root, targetPath) {
   const index = readIndex(root);
   const staged = index.staged || [];