Skip to main content

Preview and publish

A repository with the kosuke-starter layout opens on its Preview: the app running from its default branch, its Versions with Restore, Publish and its live address. A Preview / Settings switch sits at the top right, on a computer and on a phone. Settings opens the repository's settings, and the page remembers which of the two you had open.

A repository without the layout opens on Settings. Its Preview button is turned off, and its tooltip reads "Preview needs the kosuke-starter layout." followed by what the repository is missing.

Start from kosuke-starter​

In the sidebar, hover the workspace's row and press its +. The New repository dialog opens on Start from kosuke-starter.

  1. Under "What do you want to build?", describe it in a sentence, such as "A booking page for my yoga classes".
  2. Under Merge mode, keep Merge train with Go-ahead When checks pass, marked Default, or pick another. You can change it later in Settings > Merge agent.
  3. Press Create repository.

Sensei makes a private repository in Kosuke-Org from kosuke-starter, deploys it, and starts the first task on your sentence. The repository opens on its Preview while the first deploy runs, with three steps: Create, Deploy, and Start the first task. Once the deploy lands, the first task runs /kosuke:ship like any other task. When its checks pass, it merges and becomes Version 1.

If the first deploy fails, the Preview reads "Deployment failed" with Retry deploy and Open the logs, which opens Settings on its logs.

With the CLI, kosuke projects create --description "<what to build>" does the same. With Sensei, pick Build a new app, or ask it to build something: it shows the Describe card, and Create repository on it creates the repository.

The kosuke-starter layout​

The layout is what Publish needs to build the app as a Cloudflare Worker with bun and @cloudflare/vite-plugin:

  • a bun.lock and a build script,
  • @cloudflare/vite-plugin,
  • a wrangler.jsonc, wrangler.json or wrangler.toml naming main and compatibility_date, with no D1 database.

The app keeps its data in its own Turso database. The Preview and the published app share it through TURSO_DATABASE_URL and TURSO_AUTH_TOKEN. A task's sandbox never gets the live database.

Every repository made from kosuke-starter has the layout. An imported repository has it when it carries those files on the branch its Preview runs. Sensei checks the layout at that branch's latest commit, so a repository can gain or lose its Preview. Without the layout, the API refuses Versions, Restore and Publish with 409 NO_STARTER_LAYOUT.

The live preview​

The Preview shows the project's main sandbox, which runs the default branch, or the branch set in Branch tasks from under Advanced. It follows every merge by itself, usually within a minute. Every member who can open the project sees it.

  • While the sandbox starts, the Preview reads Starting. Versions and Publish work meanwhile.
  • A badge reads Version N for the latest Version, or First deploy before there is one.
  • When tasks of the repository run, a link such as "1 task running" opens Tasks.

The page has no New task button. Tasks live in the Tasks list like any other, and a task starts from its modal.

Versions​

Each task that merges into the default branch is a Version. The Versions list beside the Preview shows them newest first, each as "Version N" with its age and the task's title. The latest reads Current. A Batch pull request is one Version, titled after the tasks it carried. A merged task's modal shows See Version N in Preview, which opens the Preview on it.

With one Version there is nothing to restore yet: the list says "Restore shows here once a second Version lands." On a phone, the history button in the header opens Versions as a sheet.

Restore​

Press Restore on an earlier Version. The dialog reads "Version K's files come back as a new Version, Version N. Nothing is rewritten." Restoring also undoes the commits made on the default branch after Version K, and any commit pushed to it from outside Sensei. The earlier history stays.

Sensei writes the restore as one commit on the default branch, and the Preview follows it. If GitHub refuses, for example because the branch requires pull requests, the dialog keeps the error, naming the branch and the rule, and you can try again.

Publish​

Publish in the header puts a Version live at the repository's address, <label>.kosuke.app. A repository made from kosuke-starter is addressed by its repository's name. An imported one is addressed by the project's name and the start of its id, such as todo-app-3f9a1c2b.kosuke.app.

  1. Press Publish. A popover shows the address and Publish version N for the latest Version.
  2. Confirm with Publish. The button reads Publishing, then Live: vN.

A dot on the button means a newer Version is not live yet. When a release fails, the popover says so, and the Version before it stays live.

The popover lists the Releases. Roll back puts an earlier Release live again, and Make live a later one. Neither builds anything: the traffic switches at once. Unpublish takes the app down without deleting its data, and Publish puts it back at the same address.

A repository that lost the layout but still has a published app keeps Unpublish in its settings.

Apps became repositories​

Apps, the projects that worked in one chat, are gone. Every App became a repository:

  • It runs on Merge train with Go-ahead When checks pass.
  • Its chat is one Done task, whose history stays readable in Open chat.
  • Its Backlog items and the messages that waited Up next in its chat are Todo tasks, with their attachments.
  • A published App stays live at the same address, with its Versions and Releases.
  • Changes a running Turn had not saved went to a branch named kosuke/app-unsaved-…, with a Todo task to finish them.

Each member sees a notice on its page once, such as "tech-blog is a Repository now", with Open Tasks and Dismiss.

Next steps​