sequoia
A CLI for publishing standard.site documents to ATProto sequoia.pub
standard site lexicon cli publishing
Star 116
Fork 12
Watch

Support managing `site.standard.publication` icon via `sequoia.json` or CLI #35

Open h.olysh.it
Open opened by h.olysh.it

Currently there's no way to set the icon blob field on a site.standard.publication record using Sequoia. The field exists in the lexicon:

"icon": {
  "type": "blob",
  "accept": ["image/*"],
  "description": "Square image to identify the publication. Should be at least 256x256.",
  "maxSize": 1000000
}

Without it, Bluesky's enhanced link card renderer falls back to an auto-generated placeholder icon (a letter initial on a white background) instead of showing the publication's actual branding.

Suggested approaches (either/or):

  1. sequoia.json field — add an icon key pointing to a local image path, similar to how coverImage works for documents, and have sequoia publish (or a new sequoia init --update) upload it as a blob and patch the publication record.

  2. CLI command — a dedicated sequoia publication icon <path> (or sequoia publication update --icon <path>) that uploads the blob and calls putRecord.

Current workaround: a standalone script that calls uploadBlob + putRecord directly, invoked via a Taskfile task. It works but it's a manual step that's easy to forget when the favicon changes. See

This is particularly relevant now that Bluesky is using the icon blob for enhanced link card previews.

Let me know if a PR is welcome and I'll pull something together. I'm new to tangled.org so might be fun to try it out.

stevedylan.dev

Hey @h.olysh.it! Thanks for opening this issue. I believe Sequoia does actually support this if you run sequoia init or sequoia update as you can see here and here. It accepts an icon path that is then uploaded to the user's PDS and then that part is included in the publication record. Give it a shot and let me know if that solves the issue or if I'm missing something! 😃

h.olysh.it

Ah! Good to know! It must just be the docs are out of date as I checked this list and didn't see anything: https://sequoia.pub/config

Consider this a doc bug perhaps? Also feel free to close and take that up separately.

h.olysh.it

I think I understand the flow now -- correct me if I'm wrong:

  • The publication record is only accessible via init/update. It isn't updated as part of publish.
  • The only way to do this is via interactive prompting. I was speed running when I got started and assumed this was all driven by a config file and I could do it later.
  • The interactive nature didn't work well me my usage of a coding agent.

So -- suggestion:

  • Make any field that is asked for in sequoia init or update a config field in sequoia.json.
  • Consider making sequoia publish also update the publication record. If not, have a mode for update or init that defers to the file.
  • Document what records get updated when. I don't think I saw this in the docs but perhaps I didn't read close enough.
stevedylan.dev

Yup that’s correct! The field in the config is publicationUri which can point to an existing publication on a PDS, making it a bit simpler for migrating. Since this is a URI like at://did:plc:ia2zdnhjaokf5lazhxrmj6eu/site.standard.publication/3mbykzswhqc2x it’s not as simple as representing this as a JSON object in the config. Similar to document records it uses the tid which is not deterministic, so the state of the publication would need to be recorded in the .sequoia-state.json to track any changes and then make sure to update the existing record instead of creating a new one.

I think this is all possible, but I’m not sure the extra complexity is worth the trade off. Generally publication updates are pretty rare and it seems fitting to have manual CLI flows to create the record and have it saved as a constant. Of course I’m open to other opinions and flows that might both satisfy automation and simplicity!

h.olysh.it

@stevdylan.dev - I saw a response from you here but it is now missing. Tangled bug?

In any case, if I remember what I read, it was that, when it comes to the publication record, sequoia doesn't want to clobber existing records as users may be migrating. So really this ends up being a read/modify/write thing and there is danger of losing data. And so you don't want to make it part of publish as that makes it more dangerous.

I appreciate that as I updated the icon out of band and it didn't get clobbered!

How about this instead -- make init and update friendly to automation? Have a mode where you can pass in flags for any of the fields you want to update so you don't have to go through the interactive flow. And if the user doesn't specify a flag then the previous value is left in the record.

Clearly, at this point, I'm good but just thinking about other workflows that folks might have and helping them to (a) see where the icon path comes in and (b) automate it if they are doing things in bulk.

heaths.dev

Seems less risky to just make sure things are documented and give that as context to your agent. Mixing command line options with configuration values can get tricky e.g., what if a configuration value is required? "If it's not specified, skip it" won't work, and but do we re-prompt if the configuration value is already specified? If not, what if they want to update it? Does it work different in init vs. update and would a user expect that?

I can update the docs at https://sequoia.pub/config but I have aforementioned concerns. I think linking to https://sequoia.pub/config as context is probably your best bet. If there's enough value in skills for sequoia, perhaps a plugin for Claude Code and other agents like Copilot CLI that use Claude Code locations would make more sense?

heaths.dev

I cleaned up config a little in https://tangled.org/stevedylan.dev/sequoia/pulls/86. Might be interesting to generate token-friendly skills if that seems interesting.

But I re-read the thread and realized - the second time, after having reviewed the config changes - that the icon configuration is intentionally not part of the schema. Now I understand better what @stevedylan.dev was talking about.

Since those few fields that init prompts for aren't part of the configuration, I could see taking command line arguments and prompting as required just for those. They are separate from the actual sequoia.json configuration file.

@stevedylan.dev what do you think about including publication state in .sequoia-state.json? I started doing that for another change - I forget which - but realized later during its development I didn't need to. We could pull the icon and other information from the configured publication record and hash it just like we do content (and now including the image) to see if the record needs to be updated. If we don't have state for it - haven't synced it yet - then we don't update anything.

stevedylan.dev

I think that could work, as long as the design makes multi publication still a possibility. However I believe the original intent/idea behind the issue and suggestions was to make Sequoia more CLI argument friendly, which is possible too with a little tweaking. I primarily design Sequoia to be human interactive rather than agent friendly, but I'm not opposed to it.

Sign up or Sign in to add to the discussion.