Senso Publish

Takes a draft that has been approved and evaluated, and puts it on a public page.

This is the first outward-facing action in the whole flow. The knowledge base is private, the gap report is private, a draft is private. engine publish puts a page on a public shared domain where anyone — and every AI model — can read it.

Exit condition: a live page at a known URL, with every publish record confirmed.

Rules that always apply

"Publish it" is the consent. The destination is a choice once, then a disclosure. Approving a draft is not consent to publish it, so publishing is never rolled into approval. On the organization's first publish — nothing live on any destination — the ask presents where the page goes, what that domain is, and the other domains it could go to, in the same breath as the publish ask; the user's answer is the consent and the destination together. After that, once the user has said publish — in those words, or by taking a "publish" option they were offered — do not ask again. What remains is one line before the command: where it goes, that the page is public, whether a card attaches, that it can be pulled back. Then run it. Ask a question only when there is a real choice to make: more than one destination would be hit, a custom domain has appeared since the last publish, or a card would attach that they have not seen.

The reads are yours. The user gets the conclusion. destinations list, the selection flag, ctas for-content, ctas list — these are checks you run, not things you narrate. Someone who said "publish it" does not want eighteen rows, what selected_for_generation means, how default resolves, or how a cache works. The other domains are offered in a clause — a few names and a count — with the full list one ask away. One line before, the result after. Explain a mechanism only when they ask, or when it changed the outcome.

Read the publish records, not the success line. "Content published." reports that the request went through, not that every destination succeeded. One publish makes one record per destination, and one can fail while the others go live. The records are in the response — read them.

Live-page configuration is fenced. Several commands here rewrite pages that are already public. They run only on an explicit request, never as tidying. See Fenced off in references/after-publishing.md.

A choice is offered as options, not as a sentence. Where the harness has a structured-choice tool (Claude Code's AskUserQuestion), every two-to-four-answer decision in this file — yes/no included — goes through it: the quoted ask is the question text, each door is an option with a one-line description, the recommended one goes first. Free-text answers — a path, a figure, a verdict — stay as prose. With no such tool (Codex, Cursor), the quote is the ask, verbatim. Each ask below carries an Options: line naming its set.

Where to start

senso content verification --status draft --output table --quiet     # what is waiting
senso destinations list --output table --quiet

Before publishing

It has to have been checked — and usually that already happened

The invariant is senso-generate-verify's and it enforces it at the hand-off: the version that publishes is the version that was judged — a completed run whose subject_version_id is the draft's current version. Coming through the Verification Loop, that check has just run. Do not repeat it.

Confirm it yourself only when you were not handed the draft — a bare "publish this" in a fresh session, or a returning-user option the loop offered off a looser read. Then one call settles it:

senso content versions <contentId> --output json --quiet          # the current version, and when it was created
senso evals runs --subject-type content --from <version created_at> \
  --limit 100 --output json --quiet

• Match subject_version_id, not subject_id. Both are on the row. A completed run against an earlier version of the same item is not a pass for this one — an edit after a run is precisely what reopens it.
• evals runs is org-wide. --subject-type content filters by subject type, not by item, and there is no --subject-id filter, so every content item's runs come back together. Bound it with --from the version's created_at — a run cannot predate the version it judged, so that is exactly the window. A bare --limit bounds the organization's whole run history instead, which on an active organization returns a page with no run for this draft on it and reads as never checked. Read total against the page and use --offset if it exceeds the limit.
• No matching run, or one in band: red, means stop and hand back. Do not publish and do not evaluate here — checking belongs to senso-generate-verify. "This one hasn't been checked against your knowledge base yet — that's the step that makes it a verified source rather than just a published page."

Where it will go

senso destinations list --output table --quiet

• selected_for_generation: true means it is in the pipeline. Publishing without --publisher-ids goes to every selected destination. Name each one it will hit; show the list only if more than one is selected, or they ask.
• On a new organization nothing is selected — and a bare engine publish is refused. Every destination, citeables included, lists with selected_for_generation: false, and publishing without --publisher-ids returns a 400 ("You need at least one destination configured before you can publish"). Nothing is created. Read the flag, not the presence.
• Any shared destination can be published to by id, selected or not. That is why the answer on a new organization is citeables: the row whose slug is citeables (display_url citeables.com) — take its publisher_id and pass it with --publisher-ids. Match on the slug, not the type: every shared destination lists with type: citeables, and there are eighteen of them. It is the shared destination the product treats as the default, and the user hears "to citeables.com" — never picked silently. On the first publish the other domains are offered beside it, in a clause (below); after that, a custom domain registered since the last publish is the one thing worth raising.
• There is no CLI command that selects a destination. generate update-settings takes generation, auto-publish, schedule and content type — not publishers — and destinations add registers a custom domain rather than selecting one. Until a destination is selected in the app, --publisher-ids goes on every publish. Do not go looking for a select command.
• live_count and the last-publish timestamp per destination say what is already out there. Every live_count at 0 means this is the organization's first publish — the ask presents the destination (below).

What the domains are

Every shared destination is a domain Senso runs. citeables.com (slug citeables) is the default; codeables.dev, cucopilot.com and cited.md sit beside it, and the rest are topic domains — payroll.md, refinance.md, smbloan.md, precedent.md and others. Any of them takes a publish by publisher_id, and several at once with --publisher-ids <id> <id>.

A custom destination is a domain the organization owns, run on the same system:

senso destinations add --domain content.example.com --name "Example Citeables" --output json --quiet

Registration is synchronous; the new row appears in destinations list with its own publisher_id, and the publish passes that. --type defaults to citeables and is the right default.

Say what citeables.com is, the first time it comes up, in one clause — the user has never heard of it:

citeables.com — a domain Senso runs, not your website: a public URL that AI models can crawl and cite, where every line traces back to your own documents. Nothing on your own site changes.

Show the domains when they ask

"What are the others?", "show me the domains" — render from destinations list, one per line, display_url · name · live pages. No ids, no flag:

• citeables.com — Citeables · 0 pages live
• codeables.dev — Codeables · 0 pages live
• payroll.md — payroll.md · 0 pages live
• …

Or a domain you own — give me the hostname and I'll register it.

They pick by domain; you resolve the id.

Drop the last line inside the Verification Loop. When this list is reached from senso-verification-loop, show the Senso domains and stop there — the loop never offers destinations add, because a DNS detour is the one thing that can stall a first run. The loop's publish step carries the rule; this is the section it applies to.

What will be attached

senso ctas for-content <contentId> --output json --quiet     # default | template | none

The published page carries a call-to-action card. for-content returns selection_type: default (inherit the organization default), template (one pinned to this content), or none.

default does not mean there is a card. On a new organization the selection is default and there is no default template (ctas list is empty), so it resolves to nothing and the page publishes with no card. Read selection_type together with ctas list. The one line says "no call-to-action card" — three words, not the resolution logic.

To pin one for this content only:

senso ctas list --output table --quiet
senso ctas set-for-content <contentId> --selection template --cta-id <ctaId> --output json --quiet

--selection is default, template or none. This is per-content and safe. Changing the organization default is not — see Fenced off in references/after-publishing.md.

The ask, and the one line

The organization's first publish — every live_count is 0. The destination is a choice they have never made, so it is presented once, with the ask — unless it was presented and chosen earlier in this conversation (the Verification Loop does that at the drafting hand-off), in which case this is an ordinary publish: the one line further down, and go.

"" is ready to publish. It would go to citeables.com, a domain Senso runs — not your website; nothing on your own site changes. It's a public URL that AI models can crawl and cite, where every line traces back to your own documents. No call-to-action card, and it can be unpublished. Senso runs other domains too — codeables.dev, cucopilot.com, cited.md and a set of topic domains like payroll.md and refinance.md — and you can register a domain you own. Publish it to citeables.com, or name another?

senso engine publish --output json --quiet --data '{
  "geo_question_id": "<org prompt id>",
  "content_id": "<content id>",
  "raw_markdown": "<the approved document>",
  "seo_title": "<title>",
  "summary": "<one line>"
}'

{ "publisher": "citeables", "display_url": "https://…", "status": "success", "error_msg": "" }