Overlight: the new name, a README that shows it, docs by topic, and a green CI #21

Merged

alex merged 4 commits from overlight-rename-and-docs into main 2026-10-29 19:52:21 +01:00

Conversation 0 Commits 4 Files changed 84 +742 -389

alex commented 2026-10-29 19:49:15 +01:00

Owner

Copy link

What this does

• The app is called Overlight everywhere a person sees it: the en/es catalogues, page and window titles, setup and tour, tray, dialogs, OS notifications, the hub's announced name and CLI messages, and the Discord bot. The desktop builds are Overlight.app / Overlight-*.exe.
• No AI provider is named in generic text. "Claude agents" and "Claude Code settings" became "AI agents" and "the agent runtime", since runtimes are plugins. The Claude Code plugin keeps its name where it is the provider meant (its label, its not-installed message, its setup hint, its model names).
• A new README for people trying the app: a board screenshot up top, then a section per feature with its own screenshot, then getting started, the desktop app and the Docker hub. The 14 screenshots are WebP at 2x in docs/images, taken from a throwaway instance with demo data.
• The docs are organised by topic. Everything the old README held is kept as written, split into docs/guide/ (getting started, interface, board, agents, guard rails, workflows, projects, trackers, notifications and Discord, time and reports, themes) and docs/desktop.md, with docs/README.md as the index.
• CI is green again. The two tests that failed on every run since at least #176 pass (see below).

Deliberately unchanged

• Internal names: @kanbot/* packages, KANBOT_* variables, kanbot-hub, .kanbot/settings.json, the agent's system prompt.
• The data folder. The desktop shell pins userData to the old Kanbot folder, so existing boards, pairings and settings are found after the upgrade. The app id stays app.kanbot.desktop, so an install upgrades in place.
• The lessons heading in a project's CLAUDE.md. New files get "Lessons learned (Overlight)", but a file that already has the Kanbot heading keeps getting lessons there instead of growing a second section. A new test covers this.

Fixes found on the way

• npm run gen:plugins crashed on Windows (C:\C:\… path). It now uses fileURLToPath, with the same result on macOS and Linux.
• workspace.test.ts: the project settings file cache was keyed on mtime alone, so a rewrite within the same mtime tick (common on CI's filesystem clock) read the old parse. It is keyed on mtime + size now.
• endToEndFrames.test.ts: the 3,000-message replay test polled the whole 12 MB timeline every 5 ms on the server's thread, starving the replay it waited for (~25 s against a 30 s limit). It counts rows in SQL now and takes ~4 s.

Checks

• CI run #184 on this branch is fully green (lint, typecheck, test, SDK pack, Storybook build).
• The desktop app was not built or launched here. After merging, build it and check that an existing install still finds its board, and that an old Kanbot.app is left in Applications to delete by hand.

🤖 Generated with Claude Code

## What this does - **The app is called Overlight** everywhere a person sees it: the en/es catalogues, page and window titles, setup and tour, tray, dialogs, OS notifications, the hub's announced name and CLI messages, and the Discord bot. The desktop builds are `Overlight.app` / `Overlight-*.exe`. - **No AI provider is named in generic text.** "Claude agents" and "Claude Code settings" became "AI agents" and "the agent runtime", since runtimes are plugins. The Claude Code plugin keeps its name where it is the provider meant (its label, its not-installed message, its setup hint, its model names). - **A new README** for people trying the app: a board screenshot up top, then a section per feature with its own screenshot, then getting started, the desktop app and the Docker hub. The 14 screenshots are WebP at 2x in `docs/images`, taken from a throwaway instance with demo data. - **The docs are organised by topic.** Everything the old README held is kept as written, split into `docs/guide/` (getting started, interface, board, agents, guard rails, workflows, projects, trackers, notifications and Discord, time and reports, themes) and `docs/desktop.md`, with `docs/README.md` as the index. - **CI is green again.** The two tests that failed on every run since at least #176 pass (see below). ## Deliberately unchanged - Internal names: `@kanbot/*` packages, `KANBOT_*` variables, `kanbot-hub`, `.kanbot/settings.json`, the agent's system prompt. - **The data folder.** The desktop shell pins `userData` to the old `Kanbot` folder, so existing boards, pairings and settings are found after the upgrade. The app id stays `app.kanbot.desktop`, so an install upgrades in place. - **The lessons heading in a project's `CLAUDE.md`.** New files get "Lessons learned (Overlight)", but a file that already has the Kanbot heading keeps getting lessons there instead of growing a second section. A new test covers this. ## Fixes found on the way - `npm run gen:plugins` crashed on Windows (`C:\C:\…` path). It now uses `fileURLToPath`, with the same result on macOS and Linux. - `workspace.test.ts`: the project settings file cache was keyed on mtime alone, so a rewrite within the same mtime tick (common on CI's filesystem clock) read the old parse. It is keyed on mtime + size now. - `endToEndFrames.test.ts`: the 3,000-message replay test polled the whole 12 MB timeline every 5 ms on the server's thread, starving the replay it waited for (~25 s against a 30 s limit). It counts rows in SQL now and takes ~4 s. ## Checks - CI run #184 on this branch is fully green (lint, typecheck, test, SDK pack, Storybook build). - The desktop app was not built or launched here. After merging, build it and check that an existing install still finds its board, and that an old `Kanbot.app` is left in Applications to delete by hand. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

alex added 4 commits 2026-10-29 19:49:15 +01:00

gen-plugins finds the repository on Windows ... d92afef6dc

new URL('..', import.meta.url).pathname is /C:/Users/... on Windows, which
join() turned into C:\C:\Users\...\plugins, so npm run gen:plugins (and the
lint check that runs it) died with ENOENT. fileURLToPath gives the same
path as before on macOS and Linux.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The app is called Overlight, and its text names no AI provider ... d8d38be82e

Everything a person sees says Overlight: the en/es catalogues (values only,
keys unchanged), page and window titles, the setup and the tour, the tray,
error dialogs, OS notifications, the hub's announced name, the hub CLI's
messages and the Discord bot. electron-builder's productName and shortcut
are Overlight, so the builds are Overlight.app and Overlight-*.exe; the
appId stays app.kanbot.desktop so an install upgrades in place.

The desktop shell pins userData to the old Kanbot folder (app.setName would
otherwise move it), so existing boards, pairing and settings are found.
Lessons go under "Lessons learned (Overlight)", unless the project's
CLAUDE.md already has the Kanbot heading, which keeps receiving them.

Text that described agents as Claude's now says AI agents or the agent
runtime, since runtimes are plugins. The Claude Code plugin keeps its name
where it is the provider meant: its label, its not-installed message, its
setup hint and its model names.

Internal names stay: @kanbot/* packages, KANBOT_* variables, kanbot-hub,
.kanbot/settings.json, the data folder, the agent's system prompt.
Characterisation tests that pin the renamed text are updated, and a test
covers the old lessons heading.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README for people trying Overlight; the reference moves to docs by topic ... b31df02efa

The README now says what Overlight is and shows it: a board screenshot up
top, a section per feature with its own screenshot (planning, questions and
command approvals, reviews, the activity timeline, workflows, projects, the
command bar and list view, the timesheet and reports, a collage of twelve
themes), then getting started, the desktop app and the Docker hub. The
screenshots are WebP at 2x in docs/images, taken from a throwaway instance
with demo data.

What the old README held is kept, moved as written: the feature reference
is split into docs/guide (getting started, the interface, the board,
agents, guard rails, workflows, projects, trackers, notifications and
Discord, time and reports, themes), the desktop build and signing notes
into docs/desktop.md, and docs/README.md indexes them with the hub, plugin
SDK, code organisation and roadmap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The two tests that failed every CI run pass ... 7a3251911f

The project settings file's cache was keyed on mtime alone, so a file
rewritten within the same mtime tick (common on a container's coarse
filesystem clock) was answered from the old parse: on CI, a hand-written
file asking for a command still read as the zed preset saved just before.
It is keyed on mtime and size now, from the same stat.

The 3,000-message replay test polled the timeline every 5 ms by reading all
of it (12 MB by the end) on the server's own thread, which starved the very
replay it waited for: about 25 s against a 30 s limit here, past it on CI.
It counts the rows in SQL instead (4 s); the full read is kept for checking
the order once they are all there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

alex merged commit b26ebb447e into main 2026-10-29 19:52:21 +01:00

alex referenced this pull request from a commit 2026-10-29 19:52:22 +01:00

Merge pull request 'Overlight: the new name, a README that shows it, docs by topic, and a green CI' (#21) from overlight-rename-and-docs into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Overlight/App!21

No description provided.