An illustrated five-minute guide to writing in writui

.github/ISSUE_TEMPLATE/writing-feedback.yml

@@ -0,0 +1,46 @@
+name: Writing feedback
+description: Tell us how your first session went, or what makes you keep using writui.
+title: "Writing feedback: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for trying writui. A few sentences are enough, including if you couldn't get started.
+        This report is public. Please don't include private writing, passwords, or your vault file.
+  - type: textarea
+    id: use-case
+    attributes:
+      label: What did you want to write?
+      description: Describe the kind of writing, not its private contents.
+      placeholder: For example, a blog draft, journal entry, or work notes.
+    validations:
+      required: true
+  - type: textarea
+    id: experience
+    attributes:
+      label: How did it go?
+      description: What worked well? Where did you get stuck, or what made you stop?
+    validations:
+      required: true
+  - type: dropdown
+    id: return-use
+    attributes:
+      label: Have you come back to write again?
+      options:
+        - This was my first attempt
+        - Yes, on another day
+        - No, I stopped using it
+        - I couldn't get it running
+    validations:
+      required: true
+  - type: textarea
+    id: next-session
+    attributes:
+      label: What would help you use writui again?
+      description: A change, something to keep as it is, or a reason it isn't for you.
+  - type: input
+    id: environment
+    attributes:
+      label: Your setup (optional)
+      description: Operating system, terminal, and writui version, if you know them.
+      placeholder: For example, macOS, Ghostty, writui 0.17.0.

CONTRIBUTING.md

@@ -101,6 +101,12 @@ site/build.sh               # or build it into site/public, as Cloudflare does
 - **The demo video** on the landing page is recorded with
   [VHS](https://github.com/charmbracelet/vhs) from `site/demo.tape`; the
   tape's first lines say how to re-record it.
+- **The first-session guide's screenshots** come from
+  `site/first-session.tape`. From the repo root, run
+  `bash site/record-first-session.sh` with VHS and `cwebp` installed. It
+  records the debug app with synthetic writing in a new throwaway vault,
+  then crops and losslessly compresses the six screenshots as WebP. Raw
+  screenshots and the review GIF stay in `/tmp/writui-first-session-captures`.
 
 ## License
 

README.md

@@ -2,6 +2,8 @@
 
 A writing app for the terminal. No nonsense. Markdown. Local. Encrypted.
 
+[![Writing in writui](site/static/demo.png)](https://writui.com)
+
 - **Private.** All your posts live in one file, encrypted with your password.
   Without the password nobody can read them.
 - **Plain markdown.** You write markdown. Each post starts with a `# Title`.
@@ -99,6 +101,12 @@ cargo clippy --all-targets -- -D warnings
 
 If both finish without errors, writui's tests pass on your computer.
 
+## Try a five-minute writing session
+
+[Follow the illustrated guide](https://writui.com/blog/try-a-five-minute-writing-session/)
+to create your vault, write your first post, and keep a version to come
+back to. Then [tell us how it went](https://github.com/aakashns/writui/issues/new?template=writing-feedback.yml).
+
 ## Use
 
 Open a terminal and run:

docs/DECISIONS.md

@@ -624,3 +624,47 @@ Co-Authored-By lines. Commit bodies are wrapped at about 72 columns and
 GitHub shows every line break in release notes, so each paragraph or list
 item is joined back into one line. No "@user in #n" or "New
 contributors": it's one person's project so far.
+
+## Promotion starts with writing sessions and voluntary feedback
+
+On 2026-10-13, the creator chose regular users and useful feedback as the
+promotion priority. Start with people who already use the terminal and
+write in Markdown. The site and README offer a short session in a
+temporary vault with sample text, followed by a public GitHub feedback
+form. The form asks about the writing task, friction, and whether someone
+has returned on another day; it never asks for their actual writing or
+vault. Returning use is self-reported. Downloads, clones, and stars do not
+measure active writers.
+
+Promotion preparation and recurring research can proceed alongside app
+development. Keep code and site changes reviewable through PRs, and leave
+merging to the creator. External community submissions need an approved
+destination and message; respect each community's current rules on
+promotion and AI assistance. The creator's blog posts remain theirs.
+
+## The first-session guide is a blog post using the regular vault
+
+Later on 2026-10-13, the creator moved the guide off the landing page into
+a new blog post, "Try a five-minute writing session". Its link belongs
+directly below the demo recording. Readers should install and use writui
+normally, choose their own password, and follow illustrated steps to write
+and return to a post; they should not be asked to set up a temporary vault.
+The README links to the same guide. Its screenshots are recorded from the
+debug app with synthetic writing and an isolated throwaway vault, following
+the existing development-data rules.
+
+The creator asked for aggressive image compression and for every screenshot
+to load upfront. Ship cropped, lossless WebP images with explicit dimensions
+and eager loading, so text stays sharp and the page does not shift as
+images arrive. Keep the raw screenshots and review GIF out of the site.
+
+The guide link is the demo recording's centered, clickable caption.
+A thin white border separates each terminal screenshot from the blog
+background.
+The Markdown example has a Copy button with a brief "Copied" confirmation,
+using the same clipboard behavior as the install command.
+The introduction ends with "Here are the steps we'll follow:" and links to
+each step. Screenshot links open in a new tab, without a sentence telling
+readers to click them. The copyable example must retain its literal
+Markdown symbols and line breaks, rather than rendering headings or lists
+inside the code block.

docs/PLAN.md

@@ -12,6 +12,13 @@ file is the source of truth for what's next.
 
 ## Next up
 
+Alongside development, focus promotion on regular users and useful feedback.
+The first experiment is an illustrated "Try a five-minute writing session"
+blog post, linked in the site's demo caption and from the README, with a short
+GitHub feedback form. It guides people through using their regular vault.
+Learn where new writers get stuck and whether they return on another day.
+Keep promotion work in separate PRs from the app milestones below.
+
 The site is on Cloudflare Workers: writui.com serves it (and
 `install.sh`), and www redirects. Still to do by hand: turn off GitHub
 Pages for the repo (it's still enabled, with the writui.com domain).

docs/SPEC.md

@@ -759,6 +759,20 @@ in [DECISIONS.md](DECISIONS.md); the build order lives in [PLAN.md](PLAN.md).
   the browser allows copying; it says "Copied" for a moment). The landing
   page is kept up to date with each new feature (see AGENTS.md). "Changelog" in the menu links to the GitHub
   releases page.
+- "Try a five-minute writing session" is the demo recording's clickable,
+  centered caption. It opens a blog post with screenshots, guiding readers
+  through
+  installing the app, choosing their own vault password, writing a post,
+  saving a version, and returning to their writing. The guide uses normal
+  `writui`, with no temporary-vault setup. Screenshots are compressed WebP
+  images with explicit dimensions and a thin white border, and load upfront.
+  The Markdown example has a Copy button that briefly confirms "Copied".
+  The introduction links to each step, and screenshots open at full size
+  in a new tab when clicked.
+  The README links to the same post.
+  The guide ends with a short public GitHub feedback form asking about the
+  writing task, friction, and returning use, without collecting private
+  writing or vault files.
 - Posts live in the encrypted vault, but the blog lives in the public repo —
   so blog posts get into `site/content/blog/` via "export as markdown",
   with front matter (Zola reads YAML front matter), and are edited by

site/content/blog/try-a-five-minute-writing-session.md

@@ -0,0 +1,131 @@
++++
+title = "Try a five-minute writing session"
+description = "Create your vault, write your first post, and pick up where you left off. A step-by-step guide to writui."
+date = 2026-10-13
++++
+
+Let's write your first post in writui. You'll choose a password, put a few
+thoughts on the page, and save a version to come back to. Here are the steps
+we'll follow:
+
+1. [Install and open writui](#1-install-and-open-writui)
+2. [Choose your password](#2-choose-your-password)
+3. [Start a post](#3-start-a-post)
+4. [Write a few thoughts](#4-write-a-few-thoughts)
+5. [Keep a version](#5-keep-a-version)
+6. [Come back to it](#6-come-back-to-it)
+
+## 1. Install and open writui
+
+On macOS or Linux, paste this into your terminal and press Enter:
+
+```sh
+curl -fsSL https://writui.com/install.sh | bash
+```
+
+Follow any instructions the installer prints, then open the app:
+
+```sh
+writui
+```
+
+On Windows, follow the [build instructions](https://github.com/aakashns/writui#windows)
+first, then run `writui`.
+
+## 2. Choose your password
+
+The first time you open writui, it asks you to create your vault. This is
+where your posts and their versions are kept, encrypted on your computer.
+
+Type a password of at least eight characters, press Tab, and type it again
+in **Confirm password**. Press Enter to create your vault. You can also
+click either password box to move between them.
+
+<a target="_blank" rel="noopener" href="/blog/first-session/create-vault.webp"><img class="terminal-screenshot" src="/blog/first-session/create-vault.webp" alt="The Create your vault screen with Password and Confirm password fields" width="1000" height="360" loading="eager" decoding="async"></a>
+
+Choose a password you can remember or keep in your password manager.
+**There is no password recovery:** forgetting it means losing access to
+your writing. If you've already set up writui, enter your existing password
+to unlock it instead.
+
+## 3. Start a post
+
+You'll see your list of posts. Click **New** or press `n` to start writing.
+
+<a target="_blank" rel="noopener" href="/blog/first-session/new-post.webp"><img class="terminal-screenshot" src="/blog/first-session/new-post.webp" alt="The empty post list, with New highlighted above Import and the search field" width="1000" height="300" loading="eager" decoding="async"></a>
+
+The first line already starts with `# `. Type a title, such as
+**A little room to think**, then press Enter twice to leave a blank line
+before the body.
+
+## 4. Write a few thoughts
+
+Write about something on your mind. Or try this short example to see how
+Markdown looks:
+
+<div class="command writing-example">
+<button type="button" class="copy" data-copy="writing-example" aria-live="polite" hidden>Copy</button>
+
+<pre><code id="writing-example">Today I want to make a little room for **writing**.
+
+## Things worth noticing
+
+- A good conversation
+- An idea for tomorrow
+- A sentence I want to keep
+
+One quiet paragraph is a good start.</code></pre>
+
+</div>
+
+<a target="_blank" rel="noopener" href="/blog/first-session/writing.webp"><img class="terminal-screenshot" src="/blog/first-session/writing.webp" alt="A post titled A little room to think with a bold word, a heading, and a list" width="1000" height="350" loading="eager" decoding="async"></a>
+
+The text is formatted as you type: `**writing**` becomes bold, `##` starts a
+heading, and `-` starts a list. The Markdown marks stay visible, so you can
+always see and edit what you typed.
+
+Your post **saves automatically as you write**. You don't need to press a
+save button to keep your changes.
+
+## 5. Keep a version
+
+Press Ctrl+K to open the menu. It lists the commands and their shortcuts.
+You can click a command, move to it with the arrow keys and press Enter,
+or type part of its name to find it.
+
+<a target="_blank" rel="noopener" href="/blog/first-session/menu.webp"><img class="terminal-screenshot" src="/blog/first-session/menu.webp" alt="The command menu showing Save version, History, Export as markdown, and other commands" width="1000" height="600" loading="eager" decoding="async"></a>
+
+Choose **Save version**, or close the menu with Esc and press Ctrl+S.
+Name the version **First thoughts**, then press Enter.
+
+<a target="_blank" rel="noopener" href="/blog/first-session/save-version.webp"><img class="terminal-screenshot" src="/blog/first-session/save-version.webp" alt="The Save version dialog with First thoughts entered as the version name" width="800" height="260" loading="eager" decoding="async"></a>
+
+A version keeps a snapshot of your post. It's useful when you want to
+try a different direction without losing the earlier one. Open **History**
+from the menu, or press Ctrl+R, to see the version you just saved. Press
+Esc to return to writing.
+
+## 6. Come back to it
+
+Press Esc in the editor to return to your posts. Click your post to open it,
+or select it with the arrow keys and press Enter.
+
+<a target="_blank" rel="noopener" href="/blog/first-session/posts.webp"><img class="terminal-screenshot" src="/blog/first-session/posts.webp" alt="The post list with A little room to think saved and selected" width="1000" height="280" loading="eager" decoding="async"></a>
+
+When you're done for now, press Ctrl+Q to quit. Next time, run `writui`,
+enter your password, and you'll be back where you left off. To lock it
+without quitting, press Ctrl+O; unlocking brings you back to the same place.
+
+To keep a Markdown copy outside writui, open the menu and choose
+**Export as markdown**. Exported files are ordinary text files, so store
+them somewhere suitable for what you've written.
+
+## How did it go?
+
+[Tell us about your writing session](https://github.com/aakashns/writui/issues/new?template=writing-feedback.yml).
+What did you want to write? Did anything get in your way? Would you come
+back to it tomorrow? If you've already been using writui, we'd like to
+hear what makes you keep using it too.
+
+GitHub feedback is public, so describe your experience without including
+private writing or your password.

site/first-session.tape

@@ -0,0 +1,92 @@
+# Screenshots for the first writing session guide. From the repo root:
+#   bash site/record-first-session.sh
+# Raw screenshots and a review GIF go to /tmp/writui-first-session-captures.
+# This uses the debug app, synthetic writing, and a new throwaway vault.
+# The public guide itself uses the normal installed app and a personal password.
+
+Output "/tmp/writui-first-session-captures/flow.gif"
+
+Set Shell "bash"
+Set FontSize 22
+Set Width 1200
+Set Height 760
+Set Padding 20
+Set Framerate 10
+Set TypingSpeed 5ms
+Set Theme { "name": "writui", "background": "#111113", "foreground": "#e4e4e7", "cursor": "#e4e4e7", "selection": "#3a3a40", "black": "#18181b", "red": "#f87171", "green": "#86d39b", "yellow": "#facc15", "blue": "#7aa2f7", "magenta": "#c084fc", "cyan": "#67d4e8", "white": "#e4e4e7", "brightBlack": "#6b6b73", "brightRed": "#fca5a5", "brightGreen": "#a7e3b6", "brightYellow": "#fde68a", "brightBlue": "#a5c0fb", "brightMagenta": "#d8b4fe", "brightCyan": "#a5e8f3", "brightWhite": "#ffffff" }
+
+Hide
+Type "writui_guide_dir=$(mktemp -d /tmp/writui-guide.XXXXXX)"
+Enter
+Type 'target/debug/writui --db "$writui_guide_dir/writui.db"'
+Enter
+Sleep 1.5s
+Show
+Screenshot "/tmp/writui-first-session-captures/create-vault.png"
+Sleep 1s
+Type "writui-dev"
+Tab
+Type "writui-dev"
+Enter
+Sleep 1s
+Screenshot "/tmp/writui-first-session-captures/new-post.png"
+Sleep 1s
+Type "n"
+Sleep 300ms
+Type "A little room to think"
+Enter
+Enter
+Type "Today I want to make a little room for **writing**."
+Enter
+Enter
+Type "## Things worth noticing"
+Enter
+Enter
+Type "- A good conversation"
+Enter
+Type "- An idea for tomorrow"
+Enter
+Type "- A sentence I want to keep"
+Enter
+Enter
+Type "One quiet paragraph is a good start."
+Sleep 800ms
+Screenshot "/tmp/writui-first-session-captures/writing.png"
+Sleep 1s
+Ctrl+K
+Sleep 500ms
+Screenshot "/tmp/writui-first-session-captures/menu.png"
+Sleep 1s
+Type "save"
+Enter
+Sleep 300ms
+Type "First thoughts"
+Sleep 300ms
+Screenshot "/tmp/writui-first-session-captures/save-version.png"
+Sleep 1s
+Enter
+Sleep 500ms
+Ctrl+R
+Sleep 500ms
+Screenshot "/tmp/writui-first-session-captures/history.png"
+Sleep 1s
+Escape
+Sleep 300ms
+Escape
+Sleep 500ms
+Screenshot "/tmp/writui-first-session-captures/posts.png"
+Sleep 1s
+Enter
+Sleep 500ms
+Ctrl+O
+Sleep 500ms
+Screenshot "/tmp/writui-first-session-captures/unlock.png"
+Sleep 1s
+Type "writui-dev"
+Enter
+Sleep 1s
+Screenshot "/tmp/writui-first-session-captures/reopened.png"
+Sleep 1s
+Hide
+Ctrl+Q
+Sleep 500ms