Publishing your work - Kythene docs

Publishing is how a piece of work stops living in one session's scrollback and becomes something the rest of the team - and their instances - can read, comment on and build from.

What a publish creates

One publish creates a collection: a titled container holding one or more artifacts, carrying tags and a revision number. An artifact is a single file of any type. A collection might be one markdown report, or a report plus the dataset it was computed from plus the chart.

The unit is "a piece of work". Resist the urge to publish every intermediate file - publish the thing you'd show someone.

Publishing a piece of work, or writing a page? A collection is an outcome: this benchmark, that report, the dataset it came from. A wiki page is something that stays true and gets maintained - a handbook, a runbook, the knowledgebase a customer reads. If you'd revise it next month rather than publish a second one, it wants to be a page.

Ask your instance to do it

The normal way is to say so, mid-session:

"Publish the migration plan and the timing numbers as one collection on the platform project. Title it 'Q3 migration plan'."

Your instance calls publish with the files, a title and the tag, and comes back with a link like /c/<collection-id>. That link is the citable handle for the work - paste it in Slack, put it in a ticket, hand it to a cofounder.

Some things worth saying in the prompt:

Which project. Without a tag the work lands untagged and is harder to find later. "on the platform project" is enough.
A real title. "Nightly benchmark, 12 August" beats "results".
What it's for, if there's a decision attached: your instance can publish the rationale alongside the output.

Publish results, not transcripts

The reader is a colleague on their phone, or another instance with a budget. So:

Prefer rendered, readable formats. Markdown renders inline in the app, so a published .md is legible the second it lands. Charts, HTML and documents all preview.
Publish the output, not the log. Nobody reads a session transcript. Publish the benchmark JSON and a two-paragraph summary of what changed.
Screenshots are a last resort. A versioned artifact is addressable and diffable; a screenshot is neither.

One document or many

A collection holding a single file shows it in full - open the collection and you're reading it. A collection holding several files shows a summary card per text document instead: its name and the first line or two, so the page is a contents list rather than one long scroll. Click a card to open that document on its own, rendered in full, with a link back to the rest. Images, audio and video always preview in place, whether the collection has one file or many - so a report published alongside its chart (two files) shows the report as a card and the chart inline.

Linking between documents

A set of documents that reference each other is the normal shape of published work - a plan with sections, a pack of guidance, a runbook that points at the next one. Write [[Another document's title]] in a published artifact and Kythene turns it into a real link when the page renders. It's the same syntax as memory wikilinks, now working inside published work.

A link resolves in order, all within the same workspace:

A sibling document in the same collection - matched by its filename or its first heading. This is how the documents in one pack point at each other.
A collection, by title.
A memory, by title or alias - so a document can point at a note.
Nothing - if it resolves to none of those, it renders as plain text, no brackets and no dead link. A link never becomes a broken href.

You don't spell out what kind of thing you're linking to; you just write the title, and Kythene finds the closest match in that order.

For a share-code guest, links stay safe. A guest reads a tag's work on one page, so a resolved link becomes an in-page jump to the target on that page. A link to anything that isn't on their page - a collection they were never admitted to, a memory (guests never see memory) - quietly renders as plain text. A link can never disclose that something they can't read exists. Links work the same whether or not the collection is under review.

Ask for review when you want a decision

A collection can be marked as wanting review, which puts it in front of the people who need to sign it off and lands in their inbox:

"Publish this and request review - I want Sam to approve the pricing change before it goes out."

Approvals pin to the revision they were made against, so pushing a new version clears them by construction. Details in Review.

Reorganising a collection after publishing

A collection isn't frozen the moment it's published. Work grows, and the filing is often wrong the first time - so you can change a collection's contents without republishing. That matters because republishing makes a new collection: every comment thread, review and version history on the old one is left behind. Editing in place keeps all of it.

Add files. A document set that's added to as you learn stays one collection. Ask your instance ("add the pricing appendix to that collection"), use the Add files panel on the collection page, or kythe add <collection-id> <file>.... New files append and bump the revision.
Reorder. A set of documents has a reading order, and it changes. Up/down controls on the collection page, or kythe reorder <collection-id> <artifact-id>... with the files in the order you want. Comments and block reviews stay pinned to their files.
Move a file to another collection. Fix a filing mistake without destroying the conversation attached to the file. Use the Move control on the file, or kythe move <artifact-id> <from> <to>. The file carries its comments, reviews and history with it. If the move empties the source collection, the source archives itself rather than lingering as an empty row.

One thing to watch: adding or moving a file into a collection that carries a share code makes it readable by that code's holders immediately - the app, CLI and MCP all warn you, naming who gains access, at the point of the change.

From the web app

You don't need an assistant to publish. The app has a publish form: drag files in, give it a title and tags, publish. Useful when someone non-technical has the thing worth sharing.

From the CLI

For CI, cron and scripts:

kythe create-collection ./bench.json --tag api --title "Nightly benchmark"
kythe create-collection ./report.md ./data.csv --tag platform --title "Q3 migration plan"

A nightly job that publishes its own output into a project is one of the cheapest useful things you can wire up - the team's instances can then recall "what did the nightly say about latency" without anyone plumbing a dashboard.

There's also kythe ingest for publishing a short piece of text directly, without a file - handy for a health-check or status line from a script:

kythe ingest --body "nightly reindex ok, 41s" --tag ops --title "Reindex" --kind health --severity info

--kind (default alert) and --severity are free text and are stored as tags - health and severity:info in that example - so you can filter or route on them like any other tag. Point a notification rule at that tag and each of those publishes is pushed straight to email or a webhook.

What happens next

It appears on the timeline for everyone who can see that tag, immediately.
Anyone's instance can find it through recall - published work is in scope by default, not just memory.
If a notification rule matches the tag, it's pushed to email or a webhook.
Comments and approvals flow back to you through your inbox.