@feralfile/cli 2.6.0 → 2.8.0

package/dist/src/utilities/playlist-signer.js

@@ -1,40 +1,8 @@
+"use strict";
 /**
  * Playlist Signing Utility.
  * Uses the DP-1 v1.1.0 signing contract via the `dp1-js` package.
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 const { getPlaylistConfig } = require('../config');
 const { isDp1PlaylistSigningRole } = require('./playlist-signing-role');
 const { parsePlaylistPrivateKeyToKeyObject } = require('./ed25519-key-derive');
@@ -130,12 +98,16 @@ async function verifyPlaylist(playlist, publicKeyHex) {
  * @param {string} playlistPath - Path to playlist JSON file
  * @param {string} [privateKeyBase64] - Ed25519 private key in hex or base64 format (optional, uses config if not provided)
  * @param {string} [outputPath] - Output path (optional, overwrites input if not provided)
+ * @param {string} [roleOverride] - DP-1 signing role override
+ * @param {Object} [options] - Signing options
+ * @param {boolean} [options.replaceSignatures=false] - Drop every existing signature and sign fresh
  * @returns {Promise<Object>} Result with signed playlist
  * @returns {boolean} returns.success - Whether signing succeeded
  * @returns {Object} [returns.playlist] - Signed playlist object
+ * @returns {number} [returns.droppedSignatures] - How many stale entries were discarded
  * @returns {string} [returns.error] - Error message if failed
  */
-async function signPlaylistFile(playlistPath, privateKeyBase64, outputPath, roleOverride) {
+async function signPlaylistFile(playlistPath, privateKeyBase64, outputPath, roleOverride, options) {
     const fs = require('fs');
     const path = require('path');
     try {
@@ -156,7 +128,12 @@ async function signPlaylistFile(playlistPath, privateKeyBase64, outputPath, role
         if (!privateKey) {
             throw new Error('Private key is required for signing');
         }
-        const signedPlaylist = await buildSignedPlaylistEnvelope(playlist, privateKey, dp1, role);
+        const replaceSignatures = Boolean(options && options.replaceSignatures);
+        const droppedSignatures = replaceSignatures
+            ? (Array.isArray(playlist.signatures) ? playlist.signatures.filter(Boolean).length : 0) +
+                (typeof playlist.signature === 'string' && playlist.signature.trim() ? 1 : 0)
+            : 0;
+        const signedPlaylist = await buildSignedPlaylistEnvelope(playlist, privateKey, dp1, role, replaceSignatures);
         const verification = await verifySignedPlaylistEnvelope(signedPlaylist, dp1);
         if (!verification.valid) {
             throw new Error(`Signed playlist verification failed: ${verification.error}`);
@@ -168,6 +145,7 @@ async function signPlaylistFile(playlistPath, privateKeyBase64, outputPath, role
         return {
             success: true,
             playlist: signedPlaylist,
+            droppedSignatures,
         };
     }
     catch (error) {
@@ -181,6 +159,10 @@ module.exports = {
     signPlaylist,
     verifyPlaylist,
     signPlaylistFile,
+    // Exported for the feed-mutation intents: a delete/replace intent is signed with the same key
+    // material as a playlist, so it must accept the same encodings and raise the same guidance when the
+    // key is malformed. Duplicating the normalizer there would let the two paths drift.
+    normalizeSigningKeyToBase64Pkcs8,
 };
 function resolvePlaylistSigningRole(role) {
     const candidate = typeof role === 'string' ? role.trim() : '';
@@ -208,13 +190,25 @@ async function validatePlaylistForSigning(playlist) {
  * as dp1-js/dp1-go §7.1); prior `signatures[]` entries are kept on the returned
  * object so repeated `sign` runs accumulate endorsements instead of replacing them.
  *
+ * `replaceSignatures` discards them instead, and exists because appending is only
+ * correct while the signed content is unchanged. Editing a signed document moves
+ * bytes the earlier entries cover, so they become unverifiable — and this function's
+ * caller verifies the whole envelope before writing, which means an edited document
+ * cannot be re-signed at all without dropping them. That is the ordinary path for a
+ * feed replace: fetch the published playlist, change a field, sign fresh, PUT.
+ *
+ * The feed's own `feed` entry is dropped by the same rule rather than as a special
+ * case: it covers the pre-edit content too, and the feed appends a new one after it
+ * verifies the replacement, so carrying the old one forward can only fail.
+ *
  * @param {Object} playlist - Parsed playlist (may already include `signatures[]`)
  * @param {string} privateKey - Private key material forwarded to dp1-js
  * @param {Object} dp1 - Loaded dp1-js module
  * @param {string} role - DP-1 signing role
+ * @param {boolean} [replaceSignatures=false] - Discard existing signatures instead of appending
  * @returns {Promise<Object>} Playlist with legacy `signature` cleared and merged `signatures[]`
  */
-async function buildSignedPlaylistEnvelope(playlist, privateKey, dp1, role) {
+async function buildSignedPlaylistEnvelope(playlist, privateKey, dp1, role, replaceSignatures) {
     const playlistToSign = { ...playlist };
     delete playlistToSign.signature;
     delete playlistToSign.signatures;
@@ -222,7 +216,7 @@ async function buildSignedPlaylistEnvelope(playlist, privateKey, dp1, role) {
     // seed, PEM) works and a malformed key surfaces a clear error instead of
     // dp1-js's cryptic OpenSSL ASN.1 failure ("header too long" / "wrong tag").
     const normalizedKey = normalizeSigningKeyToBase64Pkcs8(privateKey);
-    const existingSignatures = Array.isArray(playlist.signatures)
+    const existingSignatures = !replaceSignatures && Array.isArray(playlist.signatures)
         ? playlist.signatures.filter((entry) => Boolean(entry))
         : [];
     if (typeof dp1.SignMultiEd25519 === 'function') {
@@ -261,7 +255,7 @@ async function verifySignedPlaylistEnvelope(signedPlaylist, dp1) {
  * instead of leaving a runtime require that can't resolve.
  */
 async function loadDp1() {
-    return Promise.resolve().then(() => __importStar(require('dp1-js')));
+    return import('dp1-js');
 }
 function currentTimestamp() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');

package/dist/src/utilities/playlist-signing-role.js

@@ -1,3 +1,4 @@
+"use strict";
 /**
  * Supported DP-1 playlist signing roles.
  *

package/dist/src/utilities/playlist-unpublisher.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Deletes a playlist from a DP-1 feed.
+ *
+ * `curl -X DELETE` alone answers `401`: the feed has no API key, and a delete is authorized by a signed
+ * **delete-intent** in the request body (dp1-feed-v2 `docs/api_design.md`, "DELETE — owner-bound, signed
+ * delete-intent"). The intent must name the stored `id` and `slug` exactly, carry a `created` inside the
+ * server's freshness window, and be signed by a key the stored playlist names as an owner.
+ *
+ * The delete is permanent in a stronger sense than most: it tombstones the id, and a later create naming
+ * that id is refused. There is no undo, which is why the command layer confirms before calling this.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storedOwnerKeys = void 0;
+exports.fetchPlaylistForUnpublish = fetchPlaylistForUnpublish;
+exports.unpublishPlaylist = unpublishPlaylist;
+const axios_1 = __importDefault(require("axios"));
+const feed_mutation_1 = require("./feed-mutation");
+Object.defineProperty(exports, "storedOwnerKeys", { enumerable: true, get: function () { return feed_mutation_1.storedOwnerKeys; } });
+const signing_identity_1 = require("./signing-identity");
+const config_1 = require("../config");
+/**
+ * Look up a playlist on a feed without deleting it.
+ *
+ * Exposed so the command layer can show the operator what they are about to destroy — and so the
+ * ownership refusal happens before any confirmation prompt, rather than after they have already said yes.
+ */
+async function fetchPlaylistForUnpublish(idOrUrl, feedServerUrl) {
+    return (0, feed_mutation_1.fetchStoredPlaylist)(feedServerUrl, (0, feed_mutation_1.resolvePlaylistIdentifier)(idOrUrl));
+}
+/**
+ * Delete a playlist from a feed server.
+ *
+ * Flow:
+ * 1. Resolve the id or URL the user supplied to a feed path segment.
+ * 2. `GET` the stored playlist — the intent must carry the stored id and slug, and only the stored
+ *    document says who owns it.
+ * 3. Refuse locally when the configured key is not a stored owner.
+ * 4. Build and sign the delete-intent in the `curator` role.
+ * 5. `DELETE` with the intent as the body and report the outcome.
+ *
+ * @param idOrUrl - Playlist id, slug, or a feed URL ending in either
+ * @param feedServerUrl - Feed server base URL, including `/api/v1`
+ * @param options - Optional signing-key override
+ * @returns Result carrying the deleted playlist's identity, or a diagnosis and a remedy
+ * @example
+ * const result = await unpublishPlaylist('9f...c1', 'https://feed.example.com/api/v1');
+ * if (!result.success) console.error(result.error);
+ */
+async function unpublishPlaylist(idOrUrl, feedServerUrl, options = {}) {
+    const identifier = (0, feed_mutation_1.resolvePlaylistIdentifier)(idOrUrl);
+    if (!identifier) {
+        return { success: false, error: 'No playlist id or URL was given' };
+    }
+    let privateKey;
+    try {
+        privateKey = resolveSigningKey(options.privateKey);
+    }
+    catch (error) {
+        return { success: false, error: error.message };
+    }
+    let signerDidKey;
+    try {
+        signerDidKey = (0, signing_identity_1.playlistSigningDidKey)(privateKey);
+    }
+    catch (error) {
+        return { success: false, error: error.message };
+    }
+    let stored;
+    try {
+        stored = await (0, feed_mutation_1.fetchStoredPlaylist)(feedServerUrl, identifier);
+    }
+    catch (error) {
+        return {
+            success: false,
+            ...(0, feed_mutation_1.describeFeedMutationError)(error, 'delete'),
+            feedServer: feedServerUrl,
+        };
+    }
+    const id = typeof stored.id === 'string' ? stored.id : '';
+    const slug = typeof stored.slug === 'string' ? stored.slug : '';
+    if (!id || !slug) {
+        // Both are stored verbatim from the signed document, so a feed serving one without the other is
+        // serving something this envelope cannot target. Failing here beats sending a body the feed will
+        // reject as a target mismatch, which reads like the operator's mistake.
+        return {
+            success: false,
+            error: 'The stored playlist is missing an id or slug, so a delete intent cannot target it.',
+            feedServer: feedServerUrl,
+        };
+    }
+    const refusal = await (0, feed_mutation_1.ownershipPreflight)(stored, signerDidKey, 'delete');
+    if (refusal) {
+        return { success: false, ...refusal, feedServer: feedServerUrl };
+    }
+    const created = (0, feed_mutation_1.intentTimestamp)();
+    const intent = (0, feed_mutation_1.buildDeleteIntent)(id, slug, created);
+    let body;
+    try {
+        const signature = await (0, feed_mutation_1.signIntent)(intent, privateKey);
+        body = { ...intent, signatures: [signature] };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to sign the delete intent: ${error.message}`,
+        };
+    }
+    try {
+        // axios sends a body on DELETE only when `data` is given explicitly; the feed requires one.
+        const response = await axios_1.default.delete(`${feedServerUrl}/playlists/${encodeURIComponent(id)}`, {
+            data: body,
+            headers: { 'Content-Type': 'application/json' },
+            timeout: 30000,
+        });
+        if (response.status !== 204 && response.status !== 200) {
+            return {
+                success: false,
+                error: `Unexpected response status: ${response.status}`,
+                feedServer: feedServerUrl,
+            };
+        }
+        return {
+            success: true,
+            playlistId: id,
+            slug,
+            title: typeof stored.title === 'string' ? stored.title : undefined,
+            message: 'Deleted from feed server (the id is now tombstoned and cannot be reused)',
+            feedServer: feedServerUrl,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            ...(0, feed_mutation_1.describeFeedMutationError)(error, 'delete'),
+            feedServer: feedServerUrl,
+        };
+    }
+}
+/**
+ * Resolve the signing key the same way every other signing path does.
+ *
+ * `getPlaylistConfig` already layers config.json over `PLAYLIST_PRIVATE_KEY` and screens out the sample
+ * placeholder, so going through it keeps `unpublish` signing as the identity `ff-cli status` reports.
+ */
+function resolveSigningKey(override) {
+    if (override && override.trim().length > 0) {
+        return override;
+    }
+    const configured = (0, config_1.getPlaylistConfig)().privateKey;
+    if (!configured) {
+        throw new Error('No playlist signing key is configured. A delete is authorized by a signature, so one is ' +
+            'required: run "ff-cli setup" or set playlist.privateKey in config.json.');
+    }
+    return configured;
+}

package/dist/src/utilities/playlist-verifier.js

@@ -4,39 +4,6 @@
  * Delegates signature-shape handling to dp1-js and keeps the CLI as a thin
  * orchestration layer.
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -84,10 +51,10 @@ async function verifyPlaylist(playlist, publicKey) {
         let key = publicKey?.trim() || undefined;
         if (!key) {
             try {
-                const { getPlaylistConfig } = await Promise.resolve().then(() => __importStar(require('../config')));
+                const { getPlaylistConfig } = await import('../config.js');
                 const privateKeyMaterial = getPlaylistConfig().privateKey;
                 if (privateKeyMaterial) {
-                    const { deriveEd25519PublicKeyForVerify } = await Promise.resolve().then(() => __importStar(require('./ed25519-key-derive')));
+                    const { deriveEd25519PublicKeyForVerify } = await import('./ed25519-key-derive.js');
                     key = deriveEd25519PublicKeyForVerify(privateKeyMaterial);
                 }
             }
@@ -98,7 +65,7 @@ async function verifyPlaylist(playlist, publicKey) {
         }
         if (key) {
             try {
-                const { normalizeVerifyPublicKeyToPem } = await Promise.resolve().then(() => __importStar(require('./ed25519-key-derive')));
+                const { normalizeVerifyPublicKeyToPem } = await import('./ed25519-key-derive.js');
                 key = normalizeVerifyPublicKeyToPem(key);
             }
             catch (err) {
@@ -162,7 +129,7 @@ async function parseDp1Playlist(playlist) {
  * stays lazy, so dp1-js's transitive deps don't load on unrelated commands.
  */
 async function loadDp1() {
-    return (await Promise.resolve().then(() => __importStar(require('dp1-js'))));
+    return (await import('dp1-js'));
 }
 /**
  * Verify playlist file

package/docs/CONFIGURATION.md

@@ -63,7 +63,7 @@ Used for signing DP‑1 playlists.
   `PLAYLIST_PRIVATE_KEY` even when no config file exists yet, and `ff-cli status --key <privateKey>`
   reports it for an explicit key — the one `sign --key` would use.
 
-- `playlist.role` (string): DP-1 signing role used by `ff-cli sign`. Defaults to `agent` if omitted. You can also set this via `PLAYLIST_ROLE` in `.env`. Guided `ff-cli setup`, `config validate`, and `sign --role` only accept the usual DP-1 signing roles (`agent`, `feed`, `curator`, `institution`, `licensor`). It does **not** apply to `find` and `build`, which always sign as `curator` — see [Signing role and ownership](#signing-role-and-ownership).
+- `playlist.role` (string): DP-1 signing role used by `ff-cli sign`. The shipped `config.json.example` sets `curator`, because a document signed as `agent` is ownerless to a role-aware feed and `ff-cli publish` refuses it. The code default when the key is omitted entirely is still `agent`. You can also set this via `PLAYLIST_ROLE` in `.env`. Guided `ff-cli setup`, `config validate`, and `sign --role` only accept the usual DP-1 signing roles (`agent`, `feed`, `curator`, `institution`, `licensor`). It does **not** apply to `find` and `build`, which always sign as `curator` — see [Signing role and ownership](#signing-role-and-ownership).
 
 ### Generate an Ed25519 private key
 
@@ -133,7 +133,25 @@ DP‑1 Feed API configuration.
 Endpoints used by the CLI:
 
 - `GET /api/v1/playlists` (supports `limit`, `offset`, and sorting)
-- `GET /api/v1/playlists/{id}`
+- `GET /api/v1/playlists/{id}` (`fetch`)
+- `POST /api/v1/playlists` (`publish`)
+- `PUT /api/v1/playlists/{id}` (`publish --replace`)
+- `DELETE /api/v1/playlists/{id}` (`unpublish`)
+
+No credential is configured for any of these. The feed has no API key: every write is authorized by
+signatures in the request body, and an `apiKey` left in an existing config is ignored.
+
+`playlist.privateKey` is needed only where the CLI itself has to sign at request time — `publish
+--replace` and `unpublish`, which sign the owner-bound intent that authorizes the write. A plain
+`publish` signs nothing: it uploads the `signatures[]` envelope the document already carries, so it
+works with no key configured at all (the document must have been signed at some point, by
+`ff-cli sign` or by whoever produced it, but not by this command).
+
+**Choosing between several configured servers.** Commands that address a feed (`publish`, `unpublish`,
+`fetch`, `find --publish`) take `-s, --server <index>`, a 0-based index into the list above. With one server
+configured it is optional. With more than one and no `-s`, an interactive session asks; a session with no
+terminal — a pipe, a cron job, a CI step — exits non-zero and prints the list rather than guessing, since
+defaulting to index 0 would silently write to whichever feed happens to be first.
 
 Environment variable alternative:
 
@@ -267,7 +285,7 @@ Minimal `config.json` example (selected fields):
   "defaultDuration": 10,
   "playlist": {
     "privateKey": "your_ed25519_private_key_hex_or_base64_here",
-    "role": "agent"
+    "role": "curator"
   },
   "feed": {
     "baseURLs": ["https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1"]

package/docs/EXAMPLES.md

@@ -347,10 +347,34 @@ npm run dev -- publish playlist.json
 # Direct: publish to specific server (server index 0)
 npm run dev -- publish playlist.json -s 0
 
+# Replace a playlist already stored under this document id
+npm run dev -- publish playlist.json --replace -s 0
+
 # Show help
 npm run dev -- publish --help
 ```
 
+A bare Enter at the interactive prompt selects nothing either, and fails with the list. The prompt has no
+default by design: it is being asked precisely because the CLI cannot tell which feed was meant, and
+`Number('')` is `0` — the first server, usually production.
+
+**With more than one server configured and no `-s`, a non-interactive session fails rather than
+choosing.** Under a pipe, a cron job, or a CI step there is no terminal to answer the prompt, and
+defaulting to the first server would write to production for a script that meant the other one:
+
+```
+$ ff-cli publish playlist.json < /dev/null; echo "exit=$?"
+
+Publish playlist
+
+Multiple feed servers configured (2); pass --server <index>
+  0: https://feed.feralfile.com/api/v1
+  1: http://localhost:8787
+exit=1
+```
+
+The same rule applies to `unpublish`. With a single server configured, `-s` stays optional everywhere.
+
 ### Flow
 
 1. **Verify** - Playlist structure and signatures checked; unsigned or broken playlists are rejected
@@ -519,6 +543,181 @@ only way to add one is to replace the document. Publishing is what makes that pe
 `find` and `build` sign as `curator` automatically, since they declare the key themselves. This applies to
 documents you sign by hand, where `playlist.role` (default `agent`) decides the role.
 
+## Replace or Delete a Published Playlist
+
+A feed's `PUT` and `DELETE` are **owner-bound**, and neither accepts an API key. Both carry a short-lived
+signed **intent** — `ff-cli` builds it, signs it with the configured key in the `curator` role, and sends
+it alongside (replace) or as (delete) the request body. Only a key the **stored** playlist names in
+`curators[]` can authorize either. This is the whole reason `publish` refuses a document with no
+owner-role signature: once such a playlist is created it can never be replaced or deleted.
+
+### Replace
+
+```bash
+# 1. Start from the PUBLISHED document, not a rebuilt one.
+ff-cli fetch <id> -o playlist.json -s 0
+
+# 2. Edit it. `id`, `slug`, `created` and the curators[] owner set must all stay as published.
+
+# 3. Re-sign FRESH. This flag is required here — see below.
+ff-cli sign playlist.json -r curator --replace-signatures
+
+# 4. Replace.
+ff-cli publish playlist.json --replace -s 0
+```
+
+**Step 3 needs `--replace-signatures`.** The document you fetched carries the curator's signature and
+the feed's own, both taken over the content as published. Editing it moves bytes those signatures cover,
+and `sign` **appends** rather than replaces — so a plain re-sign produces an envelope holding two stale
+entries and one good one, which `sign` then refuses to write:
+
+```
+$ ff-cli sign playlist.json -r curator
+
+Sign playlist
+
+Sign failed: Signed playlist verification failed: signed playlist is not verifiable
+
+If you edited this playlist after it was signed, the existing signatures no longer
+  cover it, and signing again cannot repair them — signing appends. Sign fresh instead:
+    ff-cli sign playlist.json -r curator --replace-signatures
+  That discards every existing entry, including any feed signature, and signs the
+  document as it stands now. It is the path a feed replace expects.
+```
+
+Signing fresh drops the feed's entry along with the curator's, which is correct: it covers the pre-edit
+content too, and the feed appends a new one of its own after it verifies the replacement.
+
+```
+$ ff-cli sign playlist.json -r curator --replace-signatures
+
+Sign playlist
+
+✓ Playlist signed and saved to: /path/to/playlist.json
+
+Playlist signed
+  Replaced 2 existing signatures
+  Signatures: 1
+```
+
+Appending stays the default, because it is right whenever the content has not changed — a second curator
+co-signing an unedited playlist keeps the first endorsement, and the payload hash excludes `signatures`
+so the earlier entry stays valid.
+
+```
+$ ff-cli publish playlist.json --replace -s 0
+
+Replace playlist
+
+Replaced
+  Playlist ID: 97595a2f-a790-477c-aa42-b4f2ec9f1e3b
+  Server: https://feed.feralfile.com/api/v1
+  Status: Replaced on feed server
+```
+
+`--replace` is never applied on your behalf. A plain `publish` of an id the feed already holds still
+fails with a conflict, because creating and overwriting are different intentions and only one of them is
+recoverable.
+
+Re-running `find` or `build` does **not** produce a replacement: each run mints a new `id`, `slug`, and
+`created`, and the feed compares all three against the stored row. `ff-cli` checks them locally and names
+the fields that moved, because the feed's own answer is a bare `400`:
+
+```
+Replace failed
+  The document changes fields a replace may not change.
+
+A replace keeps identity and ownership fixed: id, slug, and created must equal the stored
+  document's, and the curators[] owner set is immutable.
+    slug: stored "snowfro-send-receive", document "a-completely-new-slug"
+    created: stored "2026-09-07T23:32:39.660Z", document "2026-09-08T01:02:03.000Z"
+```
+
+### Delete
+
+```bash
+# id, slug, or a feed URL — all resolve to the same playlist.
+ff-cli unpublish 97595a2f-a790-477c-aa42-b4f2ec9f1e3b -s 0
+ff-cli unpublish https://feed.feralfile.com/api/v1/playlists/97595a2f-a790-477c-aa42-b4f2ec9f1e3b -s 0
+```
+
+```
+$ ff-cli unpublish 97595a2f-a790-477c-aa42-b4f2ec9f1e3b -s 0 -y
+
+Unpublish playlist
+
+Unpublished
+  Playlist ID: 97595a2f-a790-477c-aa42-b4f2ec9f1e3b
+  Slug: snowfro-send-receive
+  Server: https://feed.feralfile.com/api/v1
+  Status: Deleted from feed server (the id is now tombstoned and cannot be reused)
+```
+
+Without `-y`, `unpublish` shows the title and the server and asks, defaulting to **no**. The delete
+tombstones the id: the playlist cannot be restored, and a later publish naming that id is refused. Build
+a new playlist instead of trying to recreate it.
+
+### When ownership cannot be proved
+
+A key counts as an owner only when the **stored** playlist names it in `curators[]` **and** carries its
+valid `curator`-role signature. Being named is a claim; signing in the owner role is the proof, and the
+CLI checks both against the stored document before it signs an intent.
+
+That distinction has one large real population: playlists published while the default signing role was
+`agent`. They declare a curator and carry only that key's `agent` signature, so nothing can ever
+authorize a write to them — not even the holder of the declared key, because adding the missing proof
+would itself be a replace:
+
+```
+Unpublish failed
+  No key has proved ownership of this playlist, so none can delete it.
+
+A key counts as an owner only when it is named in curators[] AND signed the document as
+  "curator". This playlist names a curator and carries no valid curator signature
+  from that key — the shape of a playlist published while the default signing role was
+  "agent".
+  Declared:
+    did:key:z6Mkv7qJ...
+  Nothing can repair it, including holding one of those keys: adding the missing signature
+  would be a replace, and a replace needs the very proof that is missing. Publish a corrected
+  playlist under a new id instead.
+```
+
+This is why `publish` refuses to create such a document in the first place: the refusal at publish time
+is recoverable, and this one is not.
+
+### When the key is not an owner
+
+`ff-cli` reads the stored playlist before it signs anything, so this is refused locally and nothing is
+sent. The feed's own answer would be a bare `403`, naming neither the identity you offered nor the ones
+that would have worked:
+
+```
+$ ff-cli unpublish 885b2ea6-74e2-44fe-96d0-e8728f6bba9c -s 0 -y
+
+Unpublish playlist
+
+Unpublish failed
+  The configured signing key is not an owner of this playlist, so it cannot delete it.
+
+Only a key the stored playlist names in curators[] can authorize a delete; the feed derives
+  ownership from the stored document, not from a local copy.
+  Your configured identity:
+    did:key:z6MkoX8i2dynyvLh4hUHZt8b42q9uAwwCWxM4NSX4YDfMtaC
+  Stored owners:
+    did:key:z6MkoDkq5YXsFGXPiD6HDUVfze5mvhU5QF4hTy59pVVPYg82
+  Point playlist.privateKey at a key listed above (confirm any key's identity with
+  "ff-cli status --key <private key>"). Ownership cannot be granted after the fact: the owner set
+  is immutable, so a playlist signed by the wrong key stays that way.
+```
+
+Ownership cannot be granted after the fact — the owner set is immutable, and only an owner could change
+it — so the only fix is to hold a declared key. A playlist whose stored `curators[]` is **empty** is a
+harder case with the same shape: nobody owns it, no signature can ever authorize a write, and `ff-cli`
+says so rather than sending you after a key that does not exist. That is the state every playlist
+published without an owner-role signature is frozen in, and it is what the `publish` owner-role gate
+above exists to prevent.
+
 ## Complete Flow (build → validate → sign → play → publish)
 
 ```bash