From e61275576eab03404d96402e5d911ee1b3f62e73 Mon Sep 17 00:00:00 2001 From: Sean Moss-Pultz Date: Mon, 29 Jun 2026 11:33:29 +0900 Subject: [PATCH 1/3] Add Channels page (no-code + API paths) --- docs/channels/index.md | 66 ++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 67 insertions(+) create mode 100644 docs/channels/index.md diff --git a/docs/channels/index.md b/docs/channels/index.md new file mode 100644 index 0000000..b604ad8 --- /dev/null +++ b/docs/channels/index.md @@ -0,0 +1,66 @@ +# Channels + +A **channel** is a persistent, signed collection of playlists with a publisher +identity. People follow a channel on their Art Computer; when you add or update +its playlists, their devices pick up the change. A playlist is a one-time +selection — a channel is something you keep. + +Use a channel when you want an ongoing, followable presence (a gallery, a +curator, a platform) rather than a single hand-off. + +!!! note "Playlists come first" + A channel references playlists, it doesn't contain artworks directly. Build + your playlists first — see **[ff-cli](../ff-cli/index.md)** or the + **[Hosted Feed](../hosted-feed/index.md)** — then add them to a channel. + +## Two ways to make one + +=== "No-code (web)" + + [**publisher.feralfile.com**](https://publisher.feralfile.com) is the + no-code way to create and run a channel. Sign in, create a channel, give it + a title and description, add your playlists in the order you want them, and + publish. Publishing signs the channel under your publisher identity so + devices can verify it. + + This is the right path for curators and partners — no API keys, no JSON. + +=== "API (programmatic)" + + Channels are first-class on the hosted DP-1 feed. Read operations are + public; writes need a Bearer API key. + + Base URL: `https://feed.feralfile.com/api/v1` + + ```bash + # Create a channel (write — needs your API key) + curl -H "Authorization: Bearer your-api-key-here" \ + -H "Content-Type: application/json" \ + -X POST https://feed.feralfile.com/api/v1/channels \ + -d @channel.json + + # List channels (public) + curl https://feed.feralfile.com/api/v1/channels + ``` + + `channel.json` is a DP-1 channel: `title`, `slug`, a `publisher` identity, + and an ordered `playlists` array of playlist URLs, plus optional `summary`, + `coverImage`, and `curators`. The feed signs the channel server-side on + write. For the authoritative field list and every endpoint + (`GET`/`POST`/`PUT`/`PATCH`/`DELETE` on `/channels` and + `/channels/{id}`), see the feed + [OpenAPI](https://github.com/display-protocol/dp1-feed-v2/blob/main/api/openapi.yaml) + and the [channel extension schema](https://github.com/display-protocol/dp1/tree/main/extensions/channels). + +## How following works + +A channel carries at least one **feed** signature and one **publisher** +signature; conforming players verify both before they trust it. Once a device +follows your channel, the playlists you add or reorder propagate to it — that's +the difference between a channel and a one-off playlist hand-off. + +## See also + +- **[Agents Quickstart](../agents/index.md)** — set up a coding agent to build the playlists a channel points at. +- **[Hosted Feed](../hosted-feed/index.md)** — the managed endpoint channels and playlists live on. +- **[ff-cli](../ff-cli/index.md)** — build and publish the playlists. diff --git a/mkdocs.yml b/mkdocs.yml index fb9d4f2..a150376 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,6 +42,7 @@ nav: - OTA: art-computer/how-it-works/ota.md - Specification: art-computer/specification.md - Hosted Feed: hosted-feed/index.md + - Channels: channels/index.md - Contact: https://feralfile.com/legal/contact # Pages built and served but intentionally absent from the nav. From 6be88b2136fc6e85705f4d33a5143c404bd381c3 Mon Sep 17 00:00:00 2001 From: Sean Moss-Pultz Date: Mon, 29 Jun 2026 11:35:11 +0900 Subject: [PATCH 2/3] Channels: align to AGENTS.md voice (verb-first headings, one next step) --- docs/channels/index.md | 61 +++++++++++++++++++----------------------- 1 file changed, 28 insertions(+), 33 deletions(-) diff --git a/docs/channels/index.md b/docs/channels/index.md index b604ad8..d52cd91 100644 --- a/docs/channels/index.md +++ b/docs/channels/index.md @@ -1,34 +1,33 @@ # Channels -A **channel** is a persistent, signed collection of playlists with a publisher -identity. People follow a channel on their Art Computer; when you add or update -its playlists, their devices pick up the change. A playlist is a one-time -selection — a channel is something you keep. +A channel is a persistent, signed collection of playlists with a publisher +identity. People follow a channel on their Art Computer, and the playlists you +add or reorder show up on their device. A playlist is a one-time selection; a +channel is something you keep. -Use a channel when you want an ongoing, followable presence (a gallery, a -curator, a platform) rather than a single hand-off. +Reach for a channel when you want an ongoing, followable presence — a gallery, a +curator, a platform — rather than a single hand-off. -!!! note "Playlists come first" - A channel references playlists, it doesn't contain artworks directly. Build - your playlists first — see **[ff-cli](../ff-cli/index.md)** or the - **[Hosted Feed](../hosted-feed/index.md)** — then add them to a channel. +!!! note "Build your playlists first" + A channel references playlists, not artworks. Make the playlists first with + [ff-cli](../ff-cli/index.md) or the [Hosted Feed](../hosted-feed/index.md), + then point a channel at them. -## Two ways to make one +## Make a channel === "No-code (web)" - [**publisher.feralfile.com**](https://publisher.feralfile.com) is the - no-code way to create and run a channel. Sign in, create a channel, give it - a title and description, add your playlists in the order you want them, and - publish. Publishing signs the channel under your publisher identity so - devices can verify it. + [publisher.feralfile.com](https://publisher.feralfile.com) creates and + publishes channels with no API keys and no JSON. Sign in, assemble your + playlists into a channel, and publish. Publishing signs the channel under + your publisher identity so devices can verify it. - This is the right path for curators and partners — no API keys, no JSON. + This is the path for curators and partners. -=== "API (programmatic)" +=== "API" - Channels are first-class on the hosted DP-1 feed. Read operations are - public; writes need a Bearer API key. + Channels are first-class on the hosted feed. Reads are public; writes need a + Bearer API key. Base URL: `https://feed.feralfile.com/api/v1` @@ -45,22 +44,18 @@ curator, a platform) rather than a single hand-off. `channel.json` is a DP-1 channel: `title`, `slug`, a `publisher` identity, and an ordered `playlists` array of playlist URLs, plus optional `summary`, - `coverImage`, and `curators`. The feed signs the channel server-side on - write. For the authoritative field list and every endpoint - (`GET`/`POST`/`PUT`/`PATCH`/`DELETE` on `/channels` and - `/channels/{id}`), see the feed - [OpenAPI](https://github.com/display-protocol/dp1-feed-v2/blob/main/api/openapi.yaml) - and the [channel extension schema](https://github.com/display-protocol/dp1/tree/main/extensions/channels). + `coverImage`, and `curators`. The feed signs the channel on write. For the + full field list and every endpoint, see the canonical + [feed OpenAPI](https://github.com/display-protocol/dp1-feed-v2/blob/main/api/openapi.yaml) + and [channel extension schema](https://github.com/display-protocol/dp1/tree/main/extensions/channels). -## How following works +## Reach followers A channel carries at least one **feed** signature and one **publisher** signature; conforming players verify both before they trust it. Once a device -follows your channel, the playlists you add or reorder propagate to it — that's -the difference between a channel and a one-off playlist hand-off. +follows your channel, every playlist you add or reorder propagates to it — that +is what a channel gives you over a one-off playlist. -## See also +## Next step -- **[Agents Quickstart](../agents/index.md)** — set up a coding agent to build the playlists a channel points at. -- **[Hosted Feed](../hosted-feed/index.md)** — the managed endpoint channels and playlists live on. -- **[ff-cli](../ff-cli/index.md)** — build and publish the playlists. +Build the playlists your channel will point at — see [ff-cli](../ff-cli/index.md). From ab8e5543982e9065be0273545209af3aa57beed6 Mon Sep 17 00:00:00 2001 From: Sean Moss-Pultz Date: Mon, 29 Jun 2026 11:42:51 +0900 Subject: [PATCH 3/3] Channels: apply canonical engineering voice (drop em-dash/semicolon connectors) --- docs/channels/index.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/channels/index.md b/docs/channels/index.md index d52cd91..19a41bc 100644 --- a/docs/channels/index.md +++ b/docs/channels/index.md @@ -2,11 +2,11 @@ A channel is a persistent, signed collection of playlists with a publisher identity. People follow a channel on their Art Computer, and the playlists you -add or reorder show up on their device. A playlist is a one-time selection; a +add or reorder show up on their device. A playlist is a one-time selection. A channel is something you keep. -Reach for a channel when you want an ongoing, followable presence — a gallery, a -curator, a platform — rather than a single hand-off. +Reach for a channel when you want an ongoing, followable presence (a gallery, a +curator, a platform) rather than a single hand-off. !!! note "Build your playlists first" A channel references playlists, not artworks. Make the playlists first with @@ -26,7 +26,7 @@ curator, a platform — rather than a single hand-off. === "API" - Channels are first-class on the hosted feed. Reads are public; writes need a + Channels are first-class on the hosted feed. Reads are public. Writes need a Bearer API key. Base URL: `https://feed.feralfile.com/api/v1` @@ -52,10 +52,10 @@ curator, a platform — rather than a single hand-off. ## Reach followers A channel carries at least one **feed** signature and one **publisher** -signature; conforming players verify both before they trust it. Once a device -follows your channel, every playlist you add or reorder propagates to it — that -is what a channel gives you over a one-off playlist. +signature, and conforming players verify both before they trust it. Once a +device follows your channel, every playlist you add or reorder propagates to it. +That propagation is what a channel gives you over a one-off playlist. ## Next step -Build the playlists your channel will point at — see [ff-cli](../ff-cli/index.md). +Build the playlists your channel will point at. See [ff-cli](../ff-cli/index.md).