Sessions and publishing

A session

Every session starts with three calls. The server's initialize instructions tell the model to make them before anything else:

1. list_sites returns the sites your account can reach, each with id, domain, publish_url and your access.
2. select_site with site_id binds that site and returns its foundation: the brand, audiences, goals and calls to action every piece of content is written against.
3. get_skill with name: "pink-core" loads Pink's operating playbook: publishing flow, tool choice, undo, read-only rules.

Every later tool call works on the bound site. On the remote server the choice is stored for your account, so the next session (or another remote client) continues on the same site, and a call may pass site_id to target another site you can reach; the stdio bridge keeps its own choice in its state file. select_site again to switch: the new foundation replaces everything the model knew about the previous site.

add_site creates a site with you as owner and binds it in one step.

"This page"

When you have a page or topic open in Pink Editor and say this or these, the model calls get_selection, which returns what you have selected in the app with its keywords, questions and notes. If your selection is on a different site from the bound one, it says so in selection_elsewhere.

Undo

Writes to the plan are journaled. undo with scope: "last_call" or "last_turn" reverses them, and redo_last_call / redo_last_turn put them back. Some changes cannot be undone (not_undoable), and publishing is not undone: take a page down with set_article and status: "draft".

Publishing a page

add_article is the only way to publish a planned page. It is a run of several calls: the model writes the prose, and Pink does the rest.

call 1   add_article { page_id: 221 }                     → step: "queued", run_token
call 2   add_article { run_token }                        → step: "research"   (Pink researches the page's questions)
call 3   add_article { run_token }                        → step: "write_copy", payload.prompts[].prompt
         the model runs that prompt and writes markdown
call 4   add_article { run_token, payload: { copies: { "221": "…markdown…" } } }
                                                          → step: "done", payload.published[]

Each response carries { run_token, step, instruction, payload, next_call }. The model follows instruction and calls again with the run_token until step is "done".

• The model only writes prose. Pink turns it into headings and blocks, resolves internal links, collects citations and sends the page to your site. Never send JSON or blocks as copy.
• Internal links are written as [text](page:123) with the planned page's id. Pink swaps in the live URL at publish. A link to a page that is not live yet publishes as plain text, and the response warns link_target_not_live; the link appears when that page goes live.
• One page per call. A long article can be sent in pieces: append: true adds to what Pink already holds, and more: true means "not finished, don't publish yet". Leave more off the last piece.
• Pillar pages write each child page first (write_child_copy, one child per call), then the pillar itself (write_pillar_copy).
• Warnings. Read warnings[] on every response. A page with no questions marked for research skips the research step and gets no sources; the response says so.
• Time. Research takes 30 to 60 seconds per batch, and a whole run takes minutes per page. get_pipeline_status reports where a page is (idle, queued, researching, generating, done, error).

The done step lists every page and answer the run published, each with its live url. When the site has no live address yet, url is null with a note: the page is stored but not reachable.

Publishing is billed per step; see Credits.

Correcting what is live

copy is always markdown prose, never blocks; Pink restructures and republishes it with the same checks as add_article. On a self-hosted site, Pink reads the live copy back from your receiver first, so it never overwrites an edit made on the site (see Publish Protocol).

Deleting a planned page in Pink does not remove it from your site: the Publish Protocol has no delete. Pink refuses to delete a published page (delete_blocked_published); unpublish it first.