@feralfile/cli 2.7.0 → 2.8.0

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/docs/CONFIGURATION.md

@@ -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:
 

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

package/docs/PROJECT_SPEC.md

@@ -178,7 +178,39 @@ substituted for a chain the row already named.
 ### Delivery
 
 - `play` (handles playlist files, playlist URLs, and media URLs)
-- `publish`
+- `fetch`
+- `publish` (`--replace` sends an owner-bound replacement instead of a create)
+- `unpublish`
+
+### Owner-bound feed mutations
+
+Creating on a feed is open; changing or removing something is not. A feed accepts a `POST` from any
+document that is self-signed by a curator it declares, and the signer becomes that resource's owner. A
+`PUT` and a `DELETE` are authorized instead against the **stored** document's `curators[]`, and neither
+accepts an API key. Both therefore carry a signed intent — `{ action, target: { type, id, slug },
+created, signatures }`, with a `payloadHash` for replace — whose `created` must fall inside the feed's
+freshness window; the intent exists because a document's own signatures are public via `GET` and could
+otherwise be replayed to roll a resource back. The CLI proves ownership before it signs anything: it
+`GET`s the stored playlist and requires the configured key to be both named in the stored `curators[]`
+and the signer of a cryptographically valid `curator`-role signature over that stored document. Being
+named is a claim; the owner-role signature is the proof, and checking only the claim is what would let a
+legacy `agent`-signed document pass preflight and come back as a `403` reported as a missing
+declaration — the one thing not wrong with it. The three local refusals are therefore distinct: no
+declared curators, declared but never proved (terminal, and the shape of anything published while the
+default role was `agent`), and proved by a key other than this one. A `403` that survives all three is
+reported as the feed's own judgement, not as a missing declaration. This is also why `publish` refuses to
+create a document whose declared curator did not sign in the `curator` role: that refusal is
+recoverable and the resulting stored playlist would not be. A delete tombstones the id, so the operation
+is final and the id is not reusable.
+
+Editing a published playlist therefore has a required shape: `fetch` the stored document, change it,
+re-sign with `sign --replace-signatures`, then `publish --replace`. `fetch` exists because every other
+way of producing that starting file is wrong: `find` and `build` mint a new identity, and `verify` only
+reports on a document rather than saving one. Signing appends by default, which is
+correct only while the signed content is unchanged; an edit invalidates every entry the document
+carries, including the feed's own co-signature, and the envelope check refuses to persist a mix of stale
+and fresh. The fresh mode drops them all — the feed re-appends its signature after it verifies the
+replacement.
 
 ### Device operations
 

package/docs/README.md

@@ -97,7 +97,8 @@ Both paths run the same deterministic pipeline: fetch metadata, assemble a DP-1
 - `validate <file-or-url>` – Validate playlist structure only
 - `verify <file-or-url>` – Validate structure and verify signatures. On failure, the CLI labels structure issues separately from signature verification. dp1-js uses `--public-key` (or a key derived from `playlist.privateKey` / `PLAYLIST_PRIVATE_KEY` when omitted) **only** for legacy flat `signature` verification; DP-1 v1.1.0 `signatures[]` envelopes are verified without relying on that argument. If deriving or normalizing key material fails, the CLI prints a warning on stderr and continues without it (legacy verification still requires a usable key when the playlist uses a flat `signature`). The derived key is emitted as PEM. Supported key forms: hex with optional `0x`, PEM, or 32-byte raw public key as hex or base64
 - `sign <file>` – Sign playlist with a DP-1 v1.1.0 multi-signature envelope (private key string is forwarded to **`dp1-js`**; same hex or base64 PKCS#8 DER forms as `playlist.privateKey` in `./CONFIGURATION.md`). The command verifies the final envelope before writing output and refuses to persist tampered or otherwise unverifiable `signatures[]`.
-  - Options: `-k, --key <privateKey>`, `-r, --role <role>`, `-o, --output <file>`
+  - Options: `-k, --key <privateKey>`, `-r, --role <role>`, `-o, --output <file>`, `--replace-signatures`
+  - Signing **appends** by default, so repeated runs accumulate endorsements. That is only correct while the signed content is unchanged: editing a signed playlist moves bytes the earlier signatures cover, and the envelope check then refuses to write the result. `--replace-signatures` discards every existing entry — including a feed's own co-signature — and signs the document as it stands. It is the required step before `publish --replace`
 - `play <source>` – Play a playlist file, playlist URL, or media URL on an FF1 device (runs `verify` before sending; only the CLI-synthesized media URL fallback is auto-signed when a signing key is configured; use `--skip-verify` to bypass the gate)
   - Options: `-d, --device <name>`, `--skip-verify` (skip signature verification; not recommended)
 - `find <input>` – Resolve a marketplace URL, raw `chain:contract:tokenId`, or wallet address into a playable DP-1 playlist
@@ -109,7 +110,11 @@ Both paths run the same deterministic pipeline: fetch metadata, assemble a DP-1
   - DP-1 `evm` names a chain family rather than a network, so those items are skipped unless `--assume-ethereum` asserts which one they are. Getting that wrong attaches another artwork's metadata
   - Options: `-o, --output <file>`, `--force` (replace existing manifests), `--assume-ethereum`, `-v, --verbose`
 - `publish <file>` – Publish a playlist to a feed server (runs `verify` before upload and rejects unsigned or broken playlists)
-  - Options: `-s, --server <index>` (server index if multiple configured)
+  - Options: `-s, --server <index>` (server index if multiple configured), `--replace` (replace the playlist already stored under this document id instead of creating a new one)
+- `fetch <id-or-url>` – Save a published playlist from a feed server. Accepts a playlist id, a slug, or a feed URL. The document goes to `-o` when given and to stdout otherwise (status lines always go to stderr, so `ff-cli fetch <id> > playlist.json` works). This is the starting point for `publish --replace`, which requires the stored `id`, `slug`, and `created`
+  - Options: `-s, --server <index>`, `-o, --output <file>`
+- `unpublish <id-or-url>` – Delete a playlist from a feed server. Accepts a playlist id, a slug, or a feed URL. Requires the configured key to be an owner of the stored playlist, and confirms before deleting
+  - Options: `-s, --server <index>`, `-y, --yes` (skip the confirmation)
 - `ssh <enable|disable>` – Manage SSH access on an FF1 device
   - Options: `-d, --device <name>`, `--pubkey <path>`, `--ttl <duration>`
 - `device list` – List all configured FF1 devices
@@ -323,6 +328,47 @@ is configured. An `apiKey` left over in an existing config is ignored.
 }
 ```
 
+### Change or remove a published playlist
+
+A feed's `PUT` and `DELETE` are owner-bound. Neither takes an API key, and neither is authorized by the
+document alone: both carry a short-lived **intent** that ff-cli signs with the configured key in the
+`curator` role. Only a key the *stored* playlist names in `curators[]` can authorize either one, which is
+why `publish` refuses to create a playlist that carries no owner-role signature — such a document can be
+neither replaced nor deleted, ever.
+
+```bash
+# Edit a published playlist: fetch it, change the file, re-sign fresh, then replace.
+ff-cli fetch <id> -o playlist.json -s 0
+#   ...edit the title, items, or metadata...
+ff-cli sign playlist.json -r curator --replace-signatures
+ff-cli publish playlist.json --replace -s 0
+
+# Delete a published playlist (id, slug, or feed URL all work).
+ff-cli unpublish 97595a2f-a790-477c-aa42-b4f2ec9f1e3b -s 0
+ff-cli unpublish https://feed.example.com/api/v1/playlists/97595a2f-a790-477c-aa42-b4f2ec9f1e3b
+```
+
+`--replace-signatures` is not optional on that path. The document you fetched carries the curator's
+signature and the feed's, both taken over the pre-edit content; a plain `ff-cli sign` appends to them and
+the envelope check then refuses to write a file with stale entries in it. Signing fresh drops both — the
+feed re-appends its own after it verifies the replacement.
+
+`--replace` keeps identity fixed: `id`, `slug`, and `created` must equal the stored document's, and the
+`curators[]` owner set may not change. Editing a published playlist therefore means editing the document
+you published — re-running `find` or `build` mints a fresh id, slug, and `created`, which is a new
+playlist rather than a replacement. A `publish` without `--replace` is never silently upgraded to a
+replace; an id the feed already holds fails with a conflict, as before.
+
+Both verbs prove ownership locally before signing anything. 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. A playlist that declares a curator but was
+signed under another role (the shape of anything published while the default role was `agent`) can never
+be replaced or deleted by anyone, and the CLI says so rather than sending a request the feed will refuse.
+
+`unpublish` asks for confirmation first, showing the title and the server. `-y` skips it for scripts.
+Deletion is final in a way worth knowing before you run it: the feed **tombstones** the id, so the
+playlist cannot be restored and a later publish naming that id is refused. Build a new playlist instead.
+
 ### FF1 device management
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feralfile/cli",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
   "repository": {
     "type": "git",