diff --git a/.github/workflows/wiki.yml b/.github/workflows/wiki.yml
new file mode 100644
index 0000000..5324802
--- /dev/null
+++ b/.github/workflows/wiki.yml
@@ -0,0 +1,48 @@
+name: Wiki
+
+# Publishes wiki/ to the repository's GitHub wiki whenever it changes on main,
+# so the wiki's pages are reviewed in pull requests like everything else.
+# Pages deleted from wiki/ are deleted from the wiki too; edits made in the
+# GitHub wiki UI are overwritten by the next publish.
+
+on:
+  push:
+    branches: [main]
+    paths: ['wiki/**', '.github/workflows/wiki.yml']
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: wiki
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Publish wiki
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Clone the wiki
+        env:
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: git clone --depth 1 "https://x-access-token:${TOKEN}@github.com/${{ github.repository }}.wiki.git" "$RUNNER_TEMP/wiki"
+
+      - name: Copy the pages
+        run: |
+          find "$RUNNER_TEMP/wiki" -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf {} +
+          cp -R wiki/. "$RUNNER_TEMP/wiki/"
+
+      - name: Commit and push
+        working-directory: ${{ runner.temp }}/wiki
+        run: |
+          git add -A
+          if git diff --cached --quiet; then
+            echo "The wiki is up to date."
+            exit 0
+          fi
+          git -c user.name='github-actions[bot]' -c user.email='41898282+github-actions[bot]@users.noreply.github.com' \
+            commit -m "Publish wiki from ${{ github.repository }}@${GITHUB_SHA::7}"
+          git push origin HEAD
diff --git a/README.md b/README.md
index 4fe26df..5025c8c 100644
--- a/README.md
+++ b/README.md
@@ -721,3 +721,4 @@ Code map:
 | `docs/TIMESHEETS.md`              | Timesheets: rounding, trims, destinations, storage             |
 | `docs/TIME-EXTENSION.md`          | How time tracking became the devlog-time extension             |
 | `docs/BLOCK-PAGES.md`             | Block pages and todos as blocks                                |
+| `wiki/`                           | The GitHub wiki's pages: user guide, extension developer docs and API reference (see `wiki/Development.md` to publish) |
diff --git a/wiki/API-Versions.md b/wiki/API-Versions.md
new file mode 100644
index 0000000..b9f2ca7
--- /dev/null
+++ b/wiki/API-Versions.md
@@ -0,0 +1,104 @@
+# API versions
+
+The extension API is versioned separately from the app
+(`EXTENSION_API_VERSION` in `packages/core/src/extensions.ts`, `API_VERSION`
+in `@devlog/extension-api`). Every change so far has been **additive**: there
+has been no 2.0, and an extension built for 1.0 still loads in an app that
+provides 1.7.
+
+- Declare the **lowest** version you need in the manifest: `"api": "^1.6.0"`.
+- `ctx.apiVersion` tells you what the running app provides, for optional
+  features.
+
+| API | Devlog | Headline |
+|---|---|---|
+| 1.7 | 0.18 | Activity and ranges, managed canvases, sending through destinations, `openPage`, non-inherited fields |
+| 1.6 | 0.17 | Node types, canvas writes, command context/keys/menus/post, events, pick/open/highlight, tray, time providers, canvas-header views |
+| 1.5 | 0.16 | Views and `@devlog/ui` |
+| 1.4 | — | Todos; blocks inside blocks |
+| 1.3 | — | Timesheet destinations |
+| 1.2 | — | Unrestricted (trusted) extensions, `packageDir` |
+| 1.1 | — | `machine`, focus providers |
+| 1.0 | — | The base API |
+
+## 1.7
+
+- `devlog.activity(from, to)`: what the app recorded, merged with providers.
+- `devlog.range(from, to)`: day files with blocks written in a range.
+- `devlog.managedCanvas(key, { title })`: a canvas the extension keeps;
+  `addBlock` gains `kind` and free `date` there, and `editBlock` works on any
+  block there.
+- `ui.openPage(viewId)`.
+- `permissions.send`; `destinations.list()`, `preview(to, sheet)`,
+  `send(to, sheet)`; types `DestinationInfo`, `SheetToSend`.
+- Canvas fields may say `"inherited": false`.
+- Views send `key` messages for shortcuts they did not use.
+- Types: `ActivityRecord`, `ExtensionDayBlocks`.
+
+## 1.6
+
+- **Node types**: `contributes.nodeTypes`; `ExtensionCanvas.type`.
+- `devlog.createCanvas`, `updateCanvas`, `editBlock`, `promote`.
+- `devlog.onBlockAdded(cb)`.
+- Commands: a `CommandContext` argument (`source`, `canvasId`, `date`,
+  `blockId`); manifest `keybinding`, `menus` (`canvas`, `block`, `tray`),
+  `nodeType`, `post`, `tag`.
+- `ui.pick`, `ui.open`, `ui.highlight`.
+- `app.setTrayLabel`, `app.keepRunning`.
+- `activity.idleAfter(minutes)`.
+- `provide.activity(fn)` and `TimeEvent`.
+- Views: `canvasHeader` placement, `nodeType` on views, the `context`
+  message and `ViewContext`.
+
+## 1.5
+
+- `contributes.views` with placements `page`, `statusbar`, `popover`.
+- `views.handle`, `views.post`.
+- The view message protocol (`@devlog/extension-api/view`) and `@devlog/ui`.
+
+## 1.4
+
+- `devlog.todos({ doneSince })` and `ExtensionTodo`.
+- `addBlock` options `parentId` + `date` (inside a block) and `todo`.
+
+## 1.3
+
+- `contributes.destinations`, `destinations.register(id, { preview, send })`.
+- Types `DestinationSheet`, `DestinationEntry`, `DestinationLine`,
+  `SendResult`, `Destination`.
+
+## 1.2
+
+- `permissions.unrestricted` and `ctx.packageDir`.
+
+## 1.1
+
+- `ctx.machine`.
+- `provide.focus(fn)` and `FocusEvent`.
+
+## 1.0
+
+- `ctx.id`, `ctx.apiVersion`.
+- `devlog.canvases`, `field`, `days`, `blocks`, `search`, `addBlock`.
+- `settings.get` / `onChange`; `secrets.get` / `set` / `delete`.
+- `files.repo` / `files.local`.
+- `activity.on`.
+- `ui.notify`, `ui.confirm`.
+- `commands.register`.
+- Manifest: `canvasFields`, `settings`, `secrets`, `commands`, `check`,
+  `permissions.read` / `write` / `network`, `appendOnly`.
+
+## Changing the API (for Devlog contributors)
+
+1. Add the member to `packages/extension-api/src/index.ts` with a comment
+   naming the new version, and to `APP_METHODS` in `protocol.ts` if the
+   extension calls the app.
+2. Implement it in the host process (`src/main/extensions/hostProcess.ts`)
+   and the manager (`src/main/extensions/manager.ts`), filtered by the grant.
+3. Mirror it in the test harness (`packages/extension-api/src/testing.ts`).
+4. Bump `API_VERSION` and `EXTENSION_API_VERSION` together, and the version
+   in `docs/EXTENSIONS.md` and `packages/extension-api/README.md`.
+5. Cover it in `tests/extensions.test.ts` through the real host (the
+   `probe` or `shaper` fixture).
+6. Update this wiki: the [API reference](Extension-API-Reference), the
+   [types](Extension-Types) and this page.
diff --git a/wiki/Activity-and-Time-Data.md b/wiki/Activity-and-Time-Data.md
new file mode 100644
index 0000000..9dadef7
--- /dev/null
+++ b/wiki/Activity-and-Time-Data.md
@@ -0,0 +1,140 @@
+# Activity and time data
+
+Devlog keeps no clock of its own. The machine's state (locked, idle, asleep)
+is the app's; **time** and **window focus** come from extensions. This page
+covers the four pieces of API around that:
+
+| API | Direction | Since |
+|---|---|---|
+| `ctx.activity.on(cb)` | app → extension: pause and resume notices | 1.0 |
+| `ctx.activity.idleAfter(minutes)` | extension → app: when to count the machine idle | 1.6 |
+| `ctx.provide.activity(fn)` | extension → app views: time-tracking events | 1.6 |
+| `ctx.provide.focus(fn)` | extension → app views: window focus events | 1.1 |
+| `ctx.devlog.activity(from, to)` | app → extension: everything recorded, merged | 1.7 |
+
+The design is in
+[`docs/DESIGN.md` → Time](https://github.com/sdeken/devlog/blob/main/docs/DESIGN.md#time-devlog-time-and-the-activity-log)
+and [`docs/TIME-EXTENSION.md`](https://github.com/sdeken/devlog/blob/main/docs/TIME-EXTENSION.md).
+
+## Machine state: pause and resume
+
+```js
+ctx.activity.on((n) => {
+  if (n.type === 'pause') clock.pause(n.reason, n.t) // 'locked' | 'idle' | 'suspended'
+  if (n.type === 'resume') clock.resume(n.t)
+})
+```
+
+- The app watches Electron's `powerMonitor` (lock/unlock, suspend/resume)
+  and polls the system idle state every 15 seconds.
+- Pauses are tracked **per reason**: waking from sleep clears only
+  "suspended", input after idle clears only "idle", and unlocking clears
+  everything. `resume` is sent when no reason is left.
+- **Idle detection is opt-in.** Call `ctx.activity.idleAfter(minutes)`; the
+  app uses the shortest time any extension asks for (0 means never; at most
+  1440). Without any request, idleness never pauses.
+
+```js
+const idle = () => Number(ctx.settings.get('idle_minutes') ?? '10')
+ctx.activity.idleAfter(idle())
+ctx.settings.onChange(() => ctx.activity.idleAfter(idle()))
+```
+
+## Providing time: `provide.activity`
+
+An extension that tracks time gives the app its events, and the app's
+Timeline, Weekly review, Summary and Timesheet are drawn from them.
+
+```js
+ctx.provide.activity(async (fromDate, toDate) => {
+  // Every machine's events between two local dates, inclusive.
+  const out = []
+  for (const date of datesBetween(fromDate, toDate)) {
+    for (const f of await ctx.files.repo.list()) {
+      if (!f.path.endsWith(`${date}.jsonl`)) continue
+      const text = (await ctx.files.repo.readText(f.path)) ?? ''
+      for (const line of text.split('\n')) if (line) out.push(JSON.parse(line))
+    }
+  }
+  return out // TimeEvent[]
+})
+```
+
+`TimeEvent`:
+
+| `type` | Fields | Meaning |
+|---|---|---|
+| `start` | `canvasId?` | The clock started with the app (and the task it restored). |
+| `task` | `canvasId` (or `null`), `blockId?` | The active canvas changed; `null` stops it. |
+| `stop` | — | The clock stopped with the app. |
+| `heartbeat` | — | Still running. |
+
+Every event carries `t` (ISO) and `machine` (`ctx.machine` where it was
+recorded). Events of other types are ignored; so are events without a valid
+`t`.
+
+How the app uses them:
+
+- It **replays** your events together with its own record of locks, idle and
+  sleep into task segments (task → next task, stop or pause; resumed on
+  unpause), per machine, then flattens overlaps between machines (the later
+  start wins), so time is never counted twice.
+- **Heartbeats are the liveness signal.** A gap of more than two heartbeats
+  is read as "the app was not running", so a crash cannot book a weekend.
+  devlog-time writes one every five minutes, and none while paused.
+- While **any** extension provides time, the app also writes lock/idle/sleep
+  and git events to the devlog's `activity/<machine>/…` log. Without one, it
+  records nothing about time.
+- Explicit durations (`[2h]` on a block) and user corrections (`exclude`
+  events) are applied on top.
+
+Keep per-machine logs in per-machine files
+(`ctx.files.repo`, `${ctx.machine}/YYYY/MM/YYYY-MM-DD.jsonl`) and declare
+them `appendOnly`; machines then never conflict in git.
+
+Also relevant for a time tracker:
+
+- `ctx.ui.highlight(canvasId)`: mark the running task in the sidebar;
+  commits from a linked repository then land on it when it sits inside the
+  linked canvas.
+- `ctx.app.keepRunning(true)`: time accrues only while Devlog runs, so close
+  to the tray instead of quitting.
+- `ctx.app.setTrayLabel(label)`: show the running task in the tray.
+- `ctx.devlog.onBlockAdded(cb)`: devlog-time starts a task when the user
+  posts on it.
+
+## Providing focus: `provide.focus`
+
+```js
+ctx.provide.focus(async (fromDate, toDate) => readFocusLog(fromDate, toDate)) // FocusEvent[]
+```
+
+`FocusEvent` is `{ t, app, title, machine }`: the window that came to the
+front. The app cleans the stream for its views (drops shell windows such as
+the task switcher, folds flips shorter than a few seconds, merges repeats)
+but you should record it raw. `app` is cut to 200 characters and `title` to
+1000.
+
+Reading the foreground window needs a platform helper, which the sandbox
+forbids, so a focus provider normally runs **unrestricted**. devlog-focus is
+the complete example (see [Built-in Extensions](Built-in-Extensions)).
+
+## Reading it back: `devlog.activity` (1.7)
+
+```js
+const records = await ctx.devlog.activity('2026-09-21', '2026-09-27')
+const tracked = records.filter((r) => r.type === 'task')
+```
+
+Returns the app's own log merged with what providers return (time and
+focus), as `ActivityRecord`s. Filtered by the grant:
+
+- needs a read grant (`No read access` otherwise);
+- events on canvases it may not read show `canvasId: null` (git events on
+  them are dropped);
+- `focus` events only with read access to the whole devlog;
+- at most 400 days per call.
+
+Providers have 20 seconds to answer and at most 500 000 events per call are
+used. A provider that throws is logged and skipped; the views show what the
+others gave.
diff --git a/wiki/Architecture.md b/wiki/Architecture.md
new file mode 100644
index 0000000..fb1943b
--- /dev/null
+++ b/wiki/Architecture.md
@@ -0,0 +1,149 @@
+# Architecture
+
+Devlog is an Electron app over a git repository. The one rule that shapes
+everything: **only `@devlog/core` touches the repository's files**. The
+renderer never touches the file system, and extensions reach the devlog only
+through the app.
+
+The long-form rationale is
+[`docs/DESIGN.md`](https://github.com/sdeken/devlog/blob/main/docs/DESIGN.md).
+
+## Processes
+
+```
+┌──────────── renderer (sandboxed, no Node) ────────────┐
+│ React UI                                               │
+│  Composer = TipTap (ProseMirror) + @tiptap/markdown    │
+│  Feed     = marked + DOMPurify                         │
+│  Extension views: <iframe sandbox> from devlog-ext://  │
+│  window.devlog (contextBridge) ◄──── preload           │
+└──────────────────────────┬─────────────────────────────┘
+                           │ ipcRenderer.invoke / events
+┌──────────────────────────▼─────────────────────────────┐
+│ main                                                    │
+│  @devlog/core/node: the only code that touches the repo │
+│    DevlogStore   canvases, blocks, todos, assets        │
+│    RepoIndex     SQLite cache: listings + full-text     │
+│    SyncManager   simple-git: commit/fetch/rebase/push   │
+│    ActivityLog   per-machine JSON-lines log             │
+│    manifest      storage format, extensions, lockfile   │
+│  ExtensionManager ── one ExtensionHost per extension    │
+│  machine state, CommitWatcher, protocols, settings,     │
+│  updater, tray, menu                                    │
+└──────────────┬──────────────────────────────────────────┘
+               │ fork (ELECTRON_RUN_AS_NODE, --permission), IPC
+┌──────────────▼───────────────┐  ┌──────────────────────┐
+│ extension process            │  │ extension process    │  …
+│  extensionHost.js            │  │                      │
+│  evaluates main.js, ctx API  │  │                      │
+└──────────────────────────────┘  └──────────────────────┘
+```
+
+- **Renderer**: `contextIsolation`, `sandbox` and a CSP are on. It sends
+  Markdown strings and image bytes over IPC; the main process owns all paths,
+  git and the asset server. `devlog://asset/…` is the only way the page loads
+  a file from the repository, and the handler refuses anything outside it.
+- **Main**: owns the store, the index, sync, the activity log, the extension
+  manager, machine state (lock, idle, sleep), the commit watcher, settings,
+  the tray and auto-update.
+- **Extension processes**: one per running extension, a Node child of the
+  app binary under Node's permission model. See
+  [Extension Host Protocol](Extension-Host-Protocol) and
+  [Sandbox and Permissions](Sandbox-and-Permissions).
+
+## Packages
+
+| Package | Path | Role |
+|---|---|---|
+| `@devlog/core` | `packages/core/` | Data model, file formats, storage engine. A pure entry (types, formats, hierarchy helpers, timesheet rules, extension manifests and grants; used by the renderer too) and a Node entry (`@devlog/core/node`). No Electron dependency, so a CLI or API server could be another client. See [Core Library](Core-Library). |
+| `@devlog/extension-api` | `packages/extension-api/` | What extensions are written against: types, the wire protocol, view messages, the test harness. |
+| `@devlog/ui` | `packages/ui/` | React kit for extension views. |
+| the app | `src/` | Electron main (`src/main`), preload (`src/preload`), renderer (`src/renderer`), shared pure logic (`src/shared`). |
+| built-in extensions | `builtin-extensions/` | devlog-time, devlog-focus, devlog-jira, devlog-cms. |
+
+## Code map
+
+| Path | Purpose |
+|---|---|
+| `packages/core/src/format/` | Block and canvas file formats, ids, order keys, hierarchy helpers |
+| `packages/core/src/node/store.ts` | `DevlogStore`: canvases, blocks, todos, assets |
+| `packages/core/src/node/repoIndex.ts` | `RepoIndex`: SQLite cache for listings and full-text search |
+| `packages/core/src/node/sync.ts` | `SyncManager`: commit / pull / push scheduler on `simple-git` |
+| `packages/core/src/node/activityLog.ts` | Per-machine append-only activity log |
+| `packages/core/src/node/manifest.ts` | `devlog.json` (format check, extensions, settings) and `devlog.lock.json` |
+| `packages/core/src/node/extensionFiles.ts` | The file broker behind an extension's private folders |
+| `packages/core/src/extensions.ts` | Extension manifests, sources and ids, version ranges, grants |
+| `packages/core/src/timesheet.ts` | Timesheet rules: sessions, quarter-hour rounding, trims, the week's block format |
+| `packages/extension-api/src/` | `index.ts` (the API), `protocol.ts` (host wire protocol), `view.ts` (view messages), `testing.ts` (harness) |
+| `packages/ui/src/` | `bridge.ts`, `index.tsx` (hooks, components), `styles.css` |
+| `src/main/extensions/` | `install.ts` (resolve, download, verify, unpack), `host.ts` (process), `hostProcess.ts` (inside the process), `manager.ts` (consent, grants, the API as seen from the app), `localState.ts` |
+| `src/main/protocol.ts` | `devlog://asset/…` (images from the repo) and `devlog-ext://` (extension views) |
+| `src/main/ipc.ts`, `src/preload/`, `src/shared/ipc.ts` | The IPC surface exposed to the renderer as `window.devlog` |
+| `src/main/activity/commits.ts` | Commit watcher: reflogs of linked repositories → commit blocks and git events |
+| `src/main/updates.ts`, `src/shared/updates.ts` | Silent auto-update and the pure "good moment to restart" policy |
+| `src/shared/activity.ts` | Pure event → segment replay, focus cleaning, app classification, day buckets |
+| `src/shared/review.ts` | Weekly roll-up: week math, tracked / explicit / estimated time |
+| `src/shared/theme.ts` | Colour presets and derived theme variables |
+| `src/renderer/src/components/` | React UI: top bar, sidebar, canvas view, composer, settings, extension views |
+| `src/renderer/src/editor/` | TipTap extensions: highlighted code, asset images, Slack keys, smart paste |
+| `scripts/` | Built-in extension bundler, Playwright smoke test, screenshots |
+
+## The renderer's IPC surface
+
+The preload script exposes `window.devlog` (typed in
+`src/preload/index.d.ts`); channel names live in `src/shared/ipc.ts` so main,
+preload and renderer agree. Groups:
+
+| Group | Channels |
+|---|---|
+| Settings | `settings:get`, `settings:set` |
+| Repository | `repo:info`, `repo:open`, `repo:create`, `repo:setRemote`, `repo:close`, `repo:chooseDirectory`, `repo:inspectWorkingCopy`, `repo:importHistory`, `repo:reveal` |
+| Canvases | `canvases:list`, `canvas:get`, `canvas:create`, `canvas:update`, `canvas:delete`, `canvas:archive`, `surface:set`, `surface:assetSave` |
+| Blocks | `days:list`, `day:get`, `timeline:get`, `range:get`, `entry:add`, `entry:update`, `entry:delete`, `entry:move`, `entry:hide`, `entry:reorder`, `entry:search`, `asset:save` |
+| Todos | `todos:list`, `todos:add`, `todo:setDone` |
+| Activity | `activity:range`, `activity:exclude`, `activity:restore` |
+| Extensions | `ext:list`, `ext:add`, `ext:remove`, `ext:allow`, `ext:revoke`, `ext:restart`, `ext:update`, `ext:setSettings`, `ext:setSecret`, `ext:run`, `ext:githubToken`, `ext:builtins`, `ext:viewCall`, `ext:appState`, `ext:answerPick` |
+| Sync, updates, window | `sync:now`, `sync:status`, `updates:status`, `updates:check`, `updates:install`, `editor:busy`, `shell:openExternal`, `window:menuPopup`, `window:control` |
+| Events (main → renderer) | `ev:syncStatus`, `ev:entriesChanged`, `ev:repoChanged`, `ev:menu`, `ev:attachImages`, `ev:updateStatus`, `ev:extensionsChanged`, `ev:notify`, `ev:extViewMessage`, `ev:extAppState`, `ev:extPick`, `ev:extOpen` |
+
+This surface is internal to the app and changes freely; extensions never
+see it.
+
+## How a post flows
+
+1. The composer serialises TipTap's document to Markdown and calls
+   `entry:add` (images were already saved with `asset:save`).
+2. Main calls `DevlogStore.addEntry`, which appends an `add` record to the
+   day file (under a per-file lock), updates the index, and emits `change`.
+3. The `change` event nudges `SyncManager.noteChange()`; a commit follows
+   after the debounce (30 s by default).
+4. Main tells extensions listening with `onBlockAdded` that may read that
+   canvas (devlog-time starts the task if it is one).
+5. Main sends `ev:entriesChanged`; the renderer reloads the day.
+
+## Machine state and time
+
+The main process watches `powerMonitor` (lock/unlock, suspend/resume) and
+polls the idle state every 15 seconds against the idle minutes extensions
+asked for. It tells extensions (`activity.on`) and, while some extension
+provides time, writes those events to `activity/<machine>/…`. The views read
+one merged stream: the core log plus the time and focus providers' events.
+See [Activity and Time Data](Activity-and-Time-Data).
+
+## Sync
+
+`SyncManager` serialises every git run so timers, the debounce, **Sync now**
+and quit never overlap. One run: `git status` → `add -A` + commit (the
+subject names the days touched) → if a remote exists and pushing is on,
+`fetch`, `pull --rebase --autostash` if behind, `push --set-upstream` if
+ahead. A conflicting rebase is aborted and reported; the app never
+force-pushes. `GIT_TERMINAL_PROMPT=0` stops git from blocking on credentials
+and a 90 s silence timeout kills a stalled network call.
+
+| Trigger | What happens |
+|---|---|
+| A store change | Commit after a debounce (default 30 s); writes under `activity/` and `extensions/` excepted |
+| Every N minutes (default 5) | Commit if dirty, fetch, pull if behind, push |
+| **Sync now** (⌘⇧S) | The same, immediately |
+| App start | Pull |
+| App quit | Commit and push (bounded to 20 s) |
diff --git a/wiki/Built-in-Extensions.md b/wiki/Built-in-Extensions.md
new file mode 100644
index 0000000..b5c7d45
--- /dev/null
+++ b/wiki/Built-in-Extensions.md
@@ -0,0 +1,102 @@
+# Built-in extensions
+
+Four extensions ship inside the app, in
+[`builtin-extensions/`](https://github.com/sdeken/devlog/tree/main/builtin-extensions).
+They use the same API as anyone else's, so they are the best worked examples.
+A devlog enables one with `"<name>": "builtin"` in `devlog.json`; it still
+asks before it starts, and keeps its grant when the app updates it.
+
+| Extension | Id | Version | API | Runs | Read it for |
+|---|---|---|---|---|---|
+| [devlog-time](#devlog-time-time-tracking) | `builtin.devlog-time` | 1.1.0 | `^1.7.0` | sandboxed | Almost everything: node types, commands in menus, keys and the note box, every view placement, a managed canvas, providing time, sending through destinations. TypeScript + `@devlog/ui`. |
+| [devlog-focus](#devlog-focus-window-tracking) | `builtin.devlog-focus` | 1.1.0 | `^1.2.0` | unrestricted | A small unrestricted extension with a platform helper, per-machine JSON-lines files, providing focus. |
+| [devlog-jira](#devlog-jira-jira-worklogs) | `builtin.devlog-jira` | 1.1.0 | `^1.3.0` | sandboxed | A complete destination: settings, a secret, a canvas field, a `check` command, a ledger, `fetch`. |
+| [devlog-cms](#devlog-cms-cms-timesheets) | `builtin.devlog-cms` | 1.0.1 | `^1.3.0` | sandboxed | A destination that drives a web app with no API (form login, HTML parsing). |
+
+## How built-ins are built
+
+A built-in written in plain JavaScript is a folder with
+`devlog-extension.json` and `main.js`. One written in TypeScript keeps its
+sources in `src/`, and `scripts/build-builtins.mjs` (run by `npm run build`,
+`dev`, `package`, `smoke` and `screens`) bundles:
+
+- `src/main.ts` → `dist/main.js` (CommonJS for Node 20, Node built-ins only);
+- each `src/views/<view>.tsx` → `dist/views/<view>.{html,js,css}` (one IIFE
+  script and one stylesheet, React and `@devlog/ui` included).
+
+`dist/` is not committed and `src/` is not packaged. The same esbuild
+settings work for an extension of your own.
+
+## devlog-time (Time tracking)
+
+Everything about time: without it there is no task type, no Start button, no
+Timesheet or Summary, and nothing about time is recorded.
+
+| Piece | API used |
+|---|---|
+| The **task** node type (`◉`, "posting here makes it the active task") | `contributes.nodeTypes` |
+| The clock: one active task, paused while locked, idle or asleep; `start`/`task`/`stop` and a heartbeat every five minutes in `extensions/builtin.devlog-time/<machine>/…` (or on the machine only) | `activity.on`, `activity.idleAfter`, `files.repo` / `files.local`, `provide.activity` |
+| Posting on a task starts it | `devlog.onBlockAdded` |
+| Status bar item, task picker popover, Start/Stop in task headers | `views` (`statusbar`, `popover`, `canvasHeader` with `nodeType: task`), `views.handle` / `post` |
+| Stop (`Mod+Shift+.`, tray), Start a task… (tray), Start this task (canvas menu on tasks) | `commands` with `keybinding`, `menus`, `nodeType` |
+| Post as task (`Mod+Shift+Enter`, `#task`), **Make task** on a block | `commands` with `post`/`tag` and `menus: ["block"]`; `devlog.promote` |
+| New task from the picker | `devlog.createCanvas` with `type` |
+| Tray label, sidebar highlight, keep running in the tray | `app.setTrayLabel`, `ui.highlight`, `app.keepRunning` |
+| Timesheet and Summary pages (`Mod+Shift+H`) | `views` (`page`), `ui.openPage`, `devlog.activity`, `devlog.range` |
+| The Timesheets canvas: one `kind=timesheet` block per week | `devlog.managedCanvas`, `addBlock` with `kind` and `date`, `editBlock` |
+| Sending to Jira or CMS | `permissions.send`, `destinations.list` / `preview` / `send` |
+| Hour targets per canvas (weekly, monthly) | `canvasFields` with `inherited: false` |
+
+Settings: `idle_minutes` (pause after this many minutes without input) and
+`in_repo` (keep time in the devlog, synced, or on this machine only).
+
+Sources: `src/main.ts` (activation, commands, view handlers), `src/tracker.ts`
+(the clock), `src/timesheets.ts` (the Timesheets canvas and sending),
+`src/targets.ts`, `src/views/*.tsx`, `src/ui/*.tsx`. Background:
+[`docs/TIME-EXTENSION.md`](https://github.com/sdeken/devlog/blob/main/docs/TIME-EXTENSION.md),
+[`docs/TIMESHEETS.md`](https://github.com/sdeken/devlog/blob/main/docs/TIMESHEETS.md).
+
+## devlog-focus (Window tracking)
+
+Records which window is in front (app and title) while the machine is
+unlocked, for screen time on the timeline and in the review.
+
+- Runs **unrestricted** (asks to be trusted) to start a platform helper:
+  PowerShell with `GetForegroundWindow` on Windows, an `osascript` loop on
+  macOS (titles need the Accessibility permission), `xdotool` on Linux.
+- Appends `{"t","app","title"}` lines to
+  `extensions/builtin.devlog-focus/<machine>/YYYY/MM/YYYY-MM-DD.jsonl`
+  (`appendOnly: ["**/*.jsonl"]`), nothing while paused.
+- Gives the events back through `provide.focus`.
+
+## devlog-jira (Jira worklogs)
+
+A destination (`worklogs`, "Jira"): one worklog per timesheet entry on the
+entry's Jira issue.
+
+- Canvas field `issue` (e.g. `ACME-123`), usually on task canvases, inherited
+  down the tree.
+- Settings `baseurl`, `email`; secret `token`. Basic auth with email and API
+  token (Cloud), or a Bearer personal access token with no email (Data
+  Center). REST API v2.
+- `check` command tests the connection from the settings page.
+- Ledger in `extensions/builtin.devlog-jira/sent/<week>.json` (entry id →
+  issue, worklog id and what was sent), so sending again sends only
+  creates, updates and deletes.
+- `permissions.network: ["*.atlassian.net"]`, no read or write grant needed.
+
+## devlog-cms (CMS timesheets)
+
+A destination (`hours`, "CMS") for a consultancy timesheet web app that has
+no API, so it drives the web pages:
+
+- form login (`j_security_check`; cookies kept in memory for the send),
+  the week page parsed for assignment rows and each day's `timesheet_id`, and
+  each day's form submitted with `hrs_worked` in decimal hours;
+- hours per assignment (canvas field `assignment`, usually on the client)
+  per day; the preview compares with what CMS shows so only differing days
+  are sent;
+- ledger `sent/<week>.json` (assignment and day → hours) so days it filled
+  that no longer have time go back to 0;
+- settings `username`, `baseurl`; secret `password`; commands `check` and
+  `assignments`.
diff --git a/wiki/Concepts.md b/wiki/Concepts.md
new file mode 100644
index 0000000..9538bba
--- /dev/null
+++ b/wiki/Concepts.md
@@ -0,0 +1,89 @@
+# Concepts
+
+Three words cover the model: **canvas**, **block** and **task**. Extension
+authors meet all of them through the API, so the terms here are the ones the
+[API reference](Extension-API-Reference) uses.
+
+## Canvas
+
+A canvas is anything you write about: a client, a project, a topic, a task.
+
+- It has a **title**, an optional **parent** (canvases nest: client →
+  project → task, or however you slice your work), an optional **node type**,
+  a list of linked git **repositories**, an **archived** flag and
+  **fields** from extensions.
+- It has a **surface**: free Markdown above the stream (links, contacts,
+  how-tos, a research scratchpad). The surface is not dated.
+- It has a **stream**: dated blocks, one file per local day.
+- Its **id** is random (10 characters of `0-9a-z` without `i l o u`) and never
+  changes. Renaming or moving a canvas only edits its `canvas.md`.
+- **Archiving** is a flag on the canvas and everything beneath it: archived
+  canvases leave the sidebar but stay readable and searchable.
+
+In the API a canvas is an [`ExtensionCanvas`](Extension-Types#extensioncanvas).
+
+## Block
+
+A block is one post in a stream.
+
+- It has an **id** (unique within its day file), a creation time, Markdown,
+  and optionally an update time, a **kind**, a **hidden** flag and **meta**
+  (string key/value attributes).
+- **Kinds**: `note` (the default: something you wrote), `commit` (captured
+  from a linked repository, read-only), `task` (a block that was turned into a
+  task; `meta.canvas` points at the task canvas), `todo` (a block with a
+  checkbox; `meta.done` is set once ticked), `done`, `timesheet`, plus kinds of
+  an extension's own on a canvas it keeps.
+- **Every block is a page.** Blocks nest: a block written inside another has
+  a `parentId`. A block inside another is stored in its root block's day
+  file, whenever it was written, so a subtree never splits across files.
+- Blocks written by an extension carry `meta.ext = <extension id>` and are
+  read-only in the app.
+
+In the API a block is an [`ExtensionBlock`](Extension-Types#extensionblock);
+where a block lives is always the pair `(canvasId, date)`, where `date` is the
+day file (`YYYY-MM-DD`, local time).
+
+## Node type
+
+A node type is a kind of canvas that an extension gives meaning to. The app
+has no types of its own: the one that ships, **task**, belongs to the time
+extension. A canvas carries its type as `type: <extension id>/<type id>` (the
+task is written `task: true` for compatibility). A type whose extension is
+gone reads as a plain canvas. See
+[Extension Manifest → nodeTypes](Extension-Manifest#nodetypes-16).
+
+## Task
+
+A task is a canvas of the time extension's task type: something time is
+tracked against. There is **one active task** at a time. Posting on a task
+canvas, pressing Start, or making a block a task (⌘⇧Enter, `#task`, **Make
+task**) makes it active; it stays active until you start another or stop.
+Locking the machine, going idle or sleeping pauses the clock.
+
+A block with an explicit duration such as `[2h]` or `[45m]` says "the last
+two hours were this", and overrides tracked time for that window.
+
+## Todo
+
+A todo is a block of kind `todo`, at any depth. `[ ] Call Dana` posts one.
+A panel on the right gathers the open todos for the page on screen and
+everything inside it.
+
+## Activity
+
+Alongside blocks, Devlog records what happened on the machine: lock/unlock,
+idle, sleep, git events (branches, pushes, merges) and, with extensions,
+time-tracking events and the window in front. The **Timeline**, the **Weekly
+review**, the **Summary** and the **Timesheet** are drawn from it. See
+[Activity and Time Data](Activity-and-Time-Data).
+
+## Devlog, machine, sync
+
+- A **devlog** is one git repository. `devlog.json` at its root names its
+  storage format, its extensions and their settings.
+- A **machine** is one computer using the devlog. Per-machine data lives in a
+  folder named `<host>-<short id>` (`ctx.machine` in the API), so machines
+  only ever append to their own files and never conflict.
+- **Sync** commits, pulls (rebase) and pushes on a schedule. Nothing is ever
+  lost: files are on disk before git sees them.
diff --git a/wiki/Core-Library.md b/wiki/Core-Library.md
new file mode 100644
index 0000000..0762115
--- /dev/null
+++ b/wiki/Core-Library.md
@@ -0,0 +1,180 @@
+# Core library (`@devlog/core`)
+
+The data model, file format and storage engine behind Devlog. **Everything
+that reads or writes a devlog repository goes through this package**; the
+desktop app is one client of it, and a CLI or API server could be another.
+Extensions do not use it directly (they go through `ctx`), but built-ins may
+import its pure helpers (devlog-time uses `parseDurationMarker`).
+
+Source: [`packages/core`](https://github.com/sdeken/devlog/tree/main/packages/core).
+
+| Import | Contents | Runs in |
+|---|---|---|
+| `@devlog/core` | Types, block and canvas file formats, order keys, hierarchy helpers, timesheet rules, extension manifests, sources, versions and grants | Anywhere (pure; the renderer uses it) |
+| `@devlog/core/node` | `DevlogStore`, `RepoIndex`, `SyncManager`, `ActivityLog`, `devlog.json` and lockfile helpers, `ExtensionFileStore` | Node 22.13+ |
+| `@devlog/core/types` | The types alone | Anywhere |
+
+## Rules
+
+- **The files are the source of truth.** The index is a cache that can be
+  deleted and rebuilt.
+- **Only this package writes them.** Applications ask the store to add,
+  move, hide or delete a block; they never open a day file themselves.
+- **Block files are append-only.** Every change is a record appended to its
+  file; only `compact()` rewrites one. Other files (`canvas.md`, the
+  manifest) are written atomically (temp file, then rename).
+- The store emits `change` events so a sync manager can commit shortly
+  after.
+
+## Typical use
+
+```ts
+import { DevlogStore, RepoIndex, SyncManager, assertSupportedFormat } from '@devlog/core/node'
+
+const store = new DevlogStore(root)
+await store.initLayout()
+await store.upgradeStorage()        // 3 → 4: todo lists move into the streams
+await assertSupportedFormat(root)   // format 4 only; throws with a message otherwise
+
+const sync = new SyncManager(root, { intervalMinutes: 5, debounceSeconds: 30, autoPush: true, pullOnStart: true })
+const index = RepoIndex.open(dbPath, root) // optional cache; files stay the truth
+store.attachIndex(index)
+void index.refresh()
+store.on('change', () => sync.noteChange())
+await sync.start()
+
+const acme = await store.createCanvas({ title: 'Acme Corp' })
+await store.addEntry(acme.id, 'Kickoff with Dana')
+const hits = await store.search('dana')
+```
+
+## `DevlogStore`
+
+`new DevlogStore(root)`. An `EventEmitter`: `'change'` fires after every
+write with `{ kind, canvasId?, … }`. Methods that write take an optional
+`now: Date` last, for tests.
+
+### Setup
+
+| Method | Description |
+|---|---|
+| `initLayout()` | Create the layout (`devlog.json`, `.gitattributes`, …) if missing. |
+| `upgradeStorage(): Promise<number \| null>` | Upgrade format 3 to 4; returns the old format if it upgraded. |
+| `attachIndex(index \| null)` | Serve listings and search from a `RepoIndex` once built, and keep it current. |
+| `resolve(repoRel)`, `resolveAsset(repoRel)` | Map a repo-relative path to an absolute one, refusing anything outside. |
+
+### Canvases
+
+| Method | Description |
+|---|---|
+| `listCanvases(): Promise<CanvasMeta[]>` | Every canvas, archived included. |
+| `readCanvas(id): Promise<Canvas>` | Properties and surface. |
+| `resolveCanvasId(id)`, `aliasMap()` | Follow `alias` lines to current ids. |
+| `createCanvas(input: CanvasInput)` | `title`, `parentId`, `task` or `type`, `repos`, `fields`. |
+| `updateCanvas(id, patch)` | Any of the same; a field set to `''` or `null` is removed. |
+| `setCanvasArchived(id, archived): Promise<string[]>` | Archive or restore it with everything beneath; returns the ids changed. |
+| `deleteCanvas(id): Promise<number>` | |
+| `writeSurface(id, markdown)`, `saveSurfaceAsset(id, bytes, mime, name?)` | The surface and its images. |
+| `managedCanvas(owner, title?)` | Find (or with a title, make) the canvas whose `devlog.managed` field is `owner`. |
+
+### Blocks
+
+| Method | Description |
+|---|---|
+| `listDays(canvasId): Promise<DaySummary[]>` | Day files with their block counts. |
+| `readDay(canvasId, date): Promise<Day>` | One day file's blocks, in display order. |
+| `getTimeline(canvasId, { beforeDate?, days? }): Promise<Timeline>` | Newest non-empty days, oldest first, with `hasMore`. |
+| `getRange(from, to)` | Every day file (across canvases) with blocks written, or todos ticked, in the range. |
+| `search(query, limit = 200): Promise<SearchResult>` | Substring search over blocks and surfaces. |
+| `addEntry(canvasId, markdown, position?, now?, system?)` | Add a block: `position` is `{ date?, parentId?, afterId?, beforeId? }`; `system` sets a kind and meta (commits are de-duplicated by hash). |
+| `addExtensionBlock(canvasId, extensionId, markdown, meta?, now?, opts?)` | A block marked `ext=<id>` (what `ctx.devlog.addBlock` uses). |
+| `updateEntry(canvasId, date, id, markdown)` | Edit a user block (automatic blocks are refused). |
+| `updateExtensionBlock(canvasId, date, id, extensionId, markdown, now?, { any? })` | Edit a block an extension added. |
+| `setEntryHidden(canvasId, date, id, hidden)` | Hide or reveal. |
+| `reorderEntry(canvasId, date, id, { afterId?, beforeId? })` | Move within a day. |
+| `moveEntry(fromCanvasId, date, id, toCanvasId)`, `moveBlock(…)` | Move a block (with its subtree) to another canvas, or inside another block. |
+| `deleteEntry(canvasId, date, id): Promise<number>` | Delete it and everything inside; returns how many. |
+| `promoteBlock(canvasId, date, id, type)` | Turn a block into a canvas of a node type (`promoteToTask` for the task type). |
+| `saveAsset(…)` | Save a pasted image next to a day file. |
+| `compact({ quietSince, dryRun? }): Promise<CompactionReport>` | Rewrite quiet block files to their current state (not used by the app yet). |
+
+### Todos
+
+| Method | Description |
+|---|---|
+| `addTodos(canvasId, texts, { date?, parentId? })` | Add todo blocks. |
+| `setTodoDone(canvasId, date, id, done)` | Tick or untick. |
+| `listTodos({ doneSince? }): Promise<TodoRef[]>` | Open todos (and those ticked since). |
+
+## `RepoIndex`
+
+`RepoIndex.open(dbPath, root)`: a SQLite cache (Node's built-in
+`node:sqlite`) outside the repository, with a trigram FTS5 table for
+substring search. `refresh()` re-parses what changed on disk; a schema or
+repository change, or a corrupt file, just rebuilds it. The store writes
+through to it after every file write. Tests compare every indexed answer with
+a file scan.
+
+## `SyncManager`
+
+`new SyncManager(root, options)`, an `EventEmitter`.
+
+| Option | Meaning |
+|---|---|
+| `intervalMinutes` | Full sync interval |
+| `debounceSeconds` | Commit this long after the last change |
+| `autoPush` | Fetch, pull and push when a remote exists |
+| `pullOnStart` | Pull on `start()` |
+| `authorName`, `authorEmail` | Commit author |
+| `quietPaths` | Path prefixes committed with every sync but not counted as unsaved work (`activity/`, `extensions/`) |
+
+Methods: `start()`, `stop()`, `noteChange()`, `syncNow()`, `commitAll()`,
+`setRemote(url)`, `getStatus(): SyncStatus`, `updateOptions(o)`, `idle()`.
+Events: `status` (a `SyncStatus`), `synced` (a `SyncResult`),
+`remote-changes` (a pull changed the tree).
+
+## `ActivityLog`
+
+`new ActivityLog(() => root, machine)`: `append(event)` writes to this
+machine's file for the event's local day; `read(from, to)` merges every
+machine (and the pre-0.4 shared layout) and tags each event with its
+`machine`; `machines()` lists them. Helpers: `machineFolder(host, id)`,
+`datesBetween(from, to)`, `ACTIVITY_DIR`.
+
+## Manifest and lockfile
+
+| Function | Description |
+|---|---|
+| `readStorageFormat(root)` | The `format` in `devlog.json`, or null. |
+| `assertSupportedFormat(root)` | Throws a readable message for anything but format 4. |
+| `readManifest(root)`, `updateManifest(root, fn)` | Read and atomically update `devlog.json` (`DevlogManifest`). |
+| `readLockFile(root)`, `writeLockFile(root, lock)` | `devlog.lock.json` (`LockFile`, `LockEntry`). |
+| `ensureExtensionAttributes(root, id, globs)` | Add `merge=union` lines for an extension's `appendOnly` globs. |
+
+## `ExtensionFileStore`
+
+`new ExtensionFileStore(base, { maxFileBytes?, maxTotalBytes?, maxFiles?, anchor? })`:
+the broker behind `ctx.files` (`read`, `write`, `append`, `list`, `stat`,
+`remove`). See [Sandbox and Permissions → The file broker](Sandbox-and-Permissions#the-file-broker).
+
+## Pure helpers (`@devlog/core`)
+
+| Module | Highlights |
+|---|---|
+| `format/blocks.ts` | `localDate`, `dayFilePath`, `newEntryId`, image path conversion (`toRootRelative`, `toDayRelative`), marker escaping, tree helpers (`buildTree`, `descendantIds`), `parseDurationMarker` / `normalizeDurationMarker` (`[2h]`, `[45m]`), `titleFromMarkdown`, `hasTag` / `stripTag`, `splitTodoLines` |
+| `format/canvases.ts` | `STORAGE_FORMAT`, `TASK_TYPE`, `NODE_TYPE_RE`, `newCanvasId`, `canvasDir`, `canvasPath` / `canvasLabel` (walk parents for display), `ancestorIds`, `descendantCanvasIds`, `topLevelCanvasId`, `buildCanvasTree`, `inheritedField`, `parseCanvasFile` / `serializeCanvasFile` |
+| `format/oplog.ts` | `parseOps`, `replayOps`, `parseDayFile`, `serializeDayFile`, the planners (`planAdd`, `planMove`, `planNest`, `planDelete`, `planSet`, `planEdit`), `compactOps`, `BLOCK_FORMAT` |
+| `format/order.ts` | `keyBetween`, `keysBetween`, `isValidOrderKey` |
+| `timesheet.ts` | `roundToQuarterHour`, `buildSessions`, `draftEntries`, `balanceDays`, `sanitizeTimesheet`, `serializeTimesheet` / `parseTimesheet`, `MANAGED_FIELD` |
+| `extensions.ts` | `EXTENSION_API_VERSION`, `parseExtensionManifest`, `fieldProblem`, `normalizeKeybinding`, `parseExtensionEntry`, `extensionId`, `parseVersion` / `parseRange` / `satisfies` / `newestMatching`, `scopeCanvasIds`, `visibleCanvases`, `describeScope`, `sanitizeGrant` |
+
+## Tests
+
+```sh
+npx vitest run packages/core
+```
+
+They cover the file formats (including a fuzz test of marker escaping),
+every store operation, indexed-versus-scanned equivalence, git sync against
+local bare remotes, the per-machine activity log, compaction, extension
+manifests and `devlog.json`, and the timesheet rules.
diff --git a/wiki/Development.md b/wiki/Development.md
new file mode 100644
index 0000000..70668ed
--- /dev/null
+++ b/wiki/Development.md
@@ -0,0 +1,90 @@
+# Development
+
+Working on Devlog itself. For writing extensions, see
+[Extension Quickstart](Extension-Quickstart).
+
+## Setup
+
+Requirements: Node 20+ (22.13+ to run the core's index outside Electron, which
+uses `node:sqlite`), and `git` on your `PATH`.
+
+```sh
+npm install
+npm run dev          # builds the built-in extensions, then runs with hot reload
+```
+
+`DEVLOG_USER_DATA=/some/folder npm run dev` keeps a development profile
+(settings, consent, secrets, the index) away from your real one.
+
+## Scripts
+
+| Script | What it does |
+|---|---|
+| `npm run dev` | Bundle built-ins, run with hot reload (electron-vite) |
+| `npm run build` | Bundle built-ins, production build into `out/` |
+| `npm run typecheck` | `tsc` for main (`tsconfig.node.json`) and renderer (`tsconfig.web.json`) |
+| `npm test` | Vitest: file formats, store, git sync against a local bare remote, extensions through the real host, time and timesheets, updates |
+| `npm run test:watch` | The same, watching |
+| `npm run smoke` | Build, then drive the real app with Playwright: post a note, sync, show the review (needs a display; `xvfb-run` on Linux) |
+| `npm run screens` | Build, seed a demo devlog, screenshot every view in light and dark |
+| `npm run package` | Build installers into `release/` (`package:mac`, `package:win`, `package:linux`) |
+
+Run one test file: `npx vitest run tests/extensions.test.ts`; the core's:
+`npx vitest run packages/core`.
+
+## Where tests live
+
+| Path | Covers |
+|---|---|
+| `packages/core/tests/` | Formats, oplog replay and fuzzing, order keys, store operations, index equivalence, sync, activity log, compaction, manifests, timesheets |
+| `packages/extension-api/tests/` | The test harness |
+| `tests/extensions.test.ts` | Real extension processes: the `probe`, `shaper` and `trusted` fixtures in `tests/fixtures/extensions/`, the sandbox's refusals, grants, views |
+| `tests/devlog-time.test.ts` | The time extension against the harness |
+| `tests/activity.test.ts`, `review.test.ts`, `timesheet.test.ts`, `commits.test.ts`, `updates.test.ts`, `theme.test.ts` | Pure logic in `src/shared` and the commit watcher |
+
+## Conventions
+
+- **Only `@devlog/core` writes to a devlog.** New file-format behaviour goes
+  there, with tests.
+- **Pure logic lives in `src/shared` or `@devlog/core`** and is unit-tested;
+  Electron code stays thin.
+- **Extension API changes are additive** and follow the checklist in
+  [API Versions](API-Versions#changing-the-api-for-devlog-contributors).
+- Documentation lives in `README.md`, `docs/*.md` and the package READMEs;
+  this wiki summarises and links to them. Update both when behaviour
+  changes.
+
+## Releasing
+
+1. Bump `version` in `package.json` (and `package-lock.json`) and commit.
+2. Run the **Build** workflow by hand (Actions → Build → Run workflow) with
+   `release_version` set to that version; it tags the commit `vX.Y.Z`.
+   Pushing a `vX.Y.Z` tag (`npm version minor && git push --follow-tags`)
+   does the same.
+3. CI runs typecheck, unit tests, the build and the Playwright smoke test;
+   only if all pass does it package Windows and macOS builds and publish a
+   GitHub release with the installers and the `latest*.yml` manifests that
+   installed apps update from.
+
+CI does not code-sign macOS builds, so they run but do not update
+themselves; the Windows build does. Installed apps check for updates shortly
+after launch and every four hours, and restart into a new version only when
+the app is not in use (screen locked, window hidden or unfocused and idle, or
+an update waiting a day and a pause in typing), never during a sync or with
+an unsaved edit.
+
+## Publishing this wiki
+
+The wiki's pages live in the repository under `wiki/` (one Markdown file per
+page, `Home.md`, `_Sidebar.md` and `_Footer.md` included), so they are
+reviewed like code. The **Wiki** workflow (`.github/workflows/wiki.yml`)
+publishes them to the GitHub wiki whenever `wiki/` changes on `main`, and can
+be run by hand (Actions → Wiki → Run workflow).
+
+- Edit pages in `wiki/`, not in the GitHub wiki UI: each publish replaces the
+  wiki with the folder's contents, and pages deleted from the folder are
+  deleted from the wiki.
+- Page names are file names without `.md`; link between pages with
+  `[text](Page-Name)` or `[text](Page-Name#section)`.
+- The wiki must exist (create its first page once in the GitHub UI) and be
+  enabled in the repository's settings.
diff --git a/wiki/Extension-API-Reference.md b/wiki/Extension-API-Reference.md
new file mode 100644
index 0000000..f0edd56
--- /dev/null
+++ b/wiki/Extension-API-Reference.md
@@ -0,0 +1,450 @@
+# Extension API reference
+
+API version **1.7.0**. Source of truth:
+[`packages/extension-api/src/index.ts`](https://github.com/sdeken/devlog/blob/main/packages/extension-api/src/index.ts),
+where every member is commented with the version that added it. Types used
+below are described in [Extension Types](Extension-Types).
+
+## Contents
+
+- [The module](#the-module)
+- [Conventions](#conventions)
+- [`ctx` properties](#ctx-properties)
+- [`ctx.devlog`](#ctxdevlog): [reading](#reading), [writing blocks](#writing-blocks), [canvases](#canvases), [activity and ranges](#activity-and-ranges), [managed canvases](#managed-canvases), [events](#events)
+- [`ctx.settings`](#ctxsettings)
+- [`ctx.secrets`](#ctxsecrets)
+- [`ctx.files`](#ctxfiles)
+- [`ctx.activity`](#ctxactivity)
+- [`ctx.ui`](#ctxui)
+- [`ctx.app`](#ctxapp)
+- [`ctx.commands`](#ctxcommands)
+- [`ctx.views`](#ctxviews)
+- [`ctx.destinations`](#ctxdestinations)
+- [`ctx.provide`](#ctxprovide)
+- [Timeouts and limits](#timeouts-and-limits)
+
+## The module
+
+`main.js` is CommonJS and exports `activate`, and optionally `deactivate`:
+
+```ts
+export interface ExtensionModule {
+  activate(ctx: DevlogContext): void | Promise<void>
+  deactivate?(): void | Promise<void>
+}
+```
+
+```js
+exports.activate = async (ctx) => { /* register things */ }
+exports.deactivate = async () => { /* flush, close */ }
+```
+
+A bundle whose `module.exports.default` holds them (an ES module compiled to
+CommonJS) works too.
+
+- `activate` must finish within **30 seconds**; until it returns the
+  extension is "starting" and nothing is routed to it.
+- Register commands, view handlers, destinations and providers in
+  `activate`. They can be registered later, but the app only routes to a
+  handler once it has been registered.
+- `deactivate` runs when the app stops the extension (quit, revoke, removal,
+  a grant change, an update). The process exits right after it settles.
+
+## Conventions
+
+- **Everything that talks to the app is asynchronous** and returns a
+  promise, except the fire-and-forget calls marked *(no reply)* below
+  (`ui.notify`, `ui.open`, `app.*`, `views.post`, …), which return
+  immediately.
+- **Errors are `Error`s with a readable message** (`No write access to that
+  canvas`). They are meant to be shown: throw them on from a command and the
+  user sees them.
+- **Dates** are local calendar dates, `YYYY-MM-DD`. **Times** are ISO-8601
+  strings.
+- **Where a block lives** is always `(canvasId, date)`: its canvas and the
+  day file it is stored in (for a block inside another, the root block's
+  day).
+- **Values cross a process boundary** with structured clone: return plain
+  data (objects, arrays, strings, numbers, `Uint8Array`), not class instances
+  or functions.
+- **Grants** filter everything. "Readable" below means inside the read
+  scope; "writable" inside the write scope; a canvas the extension keeps
+  (`managedCanvas`) is both, whatever it was granted.
+
+## `ctx` properties
+
+| Member | Type | Since | Description |
+|---|---|---|---|
+| `ctx.id` | `string` | 1.0 | The extension's id, from where it was installed: `sdeken.devlog-jira`, `url.my-ext`, `builtin.devlog-time`. |
+| `ctx.apiVersion` | `string` | 1.0 | The app's extension API version, e.g. `1.7.0`. |
+| `ctx.machine` | `string` | 1.1 | This machine's folder name in the devlog (`<host>-<short id>`), for per-machine files. |
+| `ctx.packageDir` | `string \| null` | 1.2 | The extension's unpacked folder, for helper scripts it ships. Only when running unrestricted; `null` in the sandbox. |
+
+Feature-detect newer members by version when you support older apps:
+
+```js
+const [maj, min] = ctx.apiVersion.split('.').map(Number)
+if (maj > 1 || min >= 7) await ctx.devlog.range(from, to)
+```
+
+## `ctx.devlog`
+
+The devlog, filtered by the grant.
+
+### Reading
+
+#### `canvases(): Promise<ExtensionCanvas[]>` (1.0)
+
+Every canvas it may read or write, plus their ancestors (so it can name
+them), plus canvases it keeps. Archived canvases are included (check
+`archived`). `fields` holds only this extension's own canvas fields set on
+each canvas. The retired journal is not listed.
+
+#### `field(canvasId, key): Promise<string | null>` (1.0)
+
+One of its own canvas fields, from the canvas or the nearest ancestor that
+sets it (unless the field is `inherited: false`). `null` when none does.
+
+- Throws `No access to that canvas` for a canvas `canvases()` would not list.
+
+```js
+const issue = await ctx.devlog.field(canvasId, 'issue') // "ACME-123", inherited from the project
+```
+
+#### `days(canvasId): Promise<string[]>` (1.0)
+
+The dates of the day files that have blocks on a canvas.
+Throws `No read access to that canvas` outside the read scope.
+
+#### `blocks(canvasId, date): Promise<ExtensionBlock[]>` (1.0)
+
+A day file's blocks, in display order (depth-first; a block inside another
+has `parentId`). Throws `No read access to that canvas` outside the read
+scope.
+
+#### `search(query): Promise<ExtensionSearchResult>` (1.0)
+
+Full-text (substring) search over blocks, limited to readable canvases.
+Surfaces are not included. With no read grant it returns `{ blocks: [] }`.
+
+#### `todos(opts?): Promise<ExtensionTodo[]>` (1.4)
+
+Open todos on readable canvases, plus those ticked off since
+`opts.doneSince` (an ISO time). Each comes with its canvas, day file and the
+blocks it sits inside (`trail`). With no read grant, `[]`.
+
+### Writing blocks
+
+#### `addBlock(canvasId, markdown, opts?): Promise<{ date, block }>` (1.0, 1.4, 1.7)
+
+Adds a block to a writable canvas. By default at the end of **today**'s day
+file.
+
+| Option | Since | Meaning |
+|---|---|---|
+| `meta` | 1.0 | String attributes stored on the block. Keys `^[a-z][a-z0-9_-]{0,31}$`, not `id at parent pos kind hidden updated ext`; values are flattened to one line and cut to 500 characters. |
+| `parentId` + `date` | 1.4 | Add it inside that block (the last child). `date` is the day file the parent lives in; required with `parentId`. |
+| `todo` | 1.4 | Add it as a todo (`kind: 'todo'`). |
+| `kind` | 1.7 | Only on a canvas it keeps: a kind of its own, `^[a-z][a-z0-9-]{0,31}$`, not `note todo task commit done`. |
+| `date` alone | 1.7 | Only on a canvas it keeps: the day file to add to. Elsewhere `date` without `parentId` is ignored (today is used). |
+
+The block gets `meta.ext = ctx.id`. Its text is read-only in the app (a todo
+can still be ticked). Markdown must be non-blank and at most 100 000
+characters.
+
+Errors: `No write access to that canvas`; `devlog.addBlock: a block added
+inside another needs that block's date`; `devlog.addBlock: a kind only on a
+canvas it keeps`; `devlog.addBlock: not a kind it may use: …`; `Not a
+metadata key: …`; `Cannot add an empty block`; `That block is too long`.
+
+Blocks it adds do **not** fire other extensions' `onBlockAdded`
+listeners (those are for blocks people post).
+
+```js
+const { date, block } = await ctx.devlog.addBlock(canvasId, 'Deployed **v2.3** to staging', { meta: { env: 'staging' } })
+await ctx.devlog.addBlock(canvasId, 'Check the error rate tomorrow', { parentId: block.id, date, todo: true })
+```
+
+#### `editBlock(canvasId, date, blockId, markdown): Promise<ExtensionBlock>` (1.6)
+
+Changes the text of a block **it added** (any block on a canvas it keeps).
+Throws `Only blocks it added`, `Entry … not found on …`, `No write access to
+that canvas`.
+
+#### `promote(canvasId, date, blockId, { type }): Promise<{ canvas, block }>` (1.6)
+
+Turns a block into a canvas of one of its own node types, just inside the
+block's canvas: the new canvas is titled from the block's first sentence,
+what was written inside the block moves there, and the block becomes the
+link to it (`kind: 'task'`, `meta.canvas`). A block that already links to a
+canvas returns that canvas. Needs write access to `canvasId`.
+
+`type` is one of its node type ids (`task`) or the full name
+(`builtin.devlog-time/task`); anything else throws `"…" is not one of its
+node types (contributes.nodeTypes)`.
+
+### Canvases
+
+#### `createCanvas({ title, parentId?, type? }): Promise<ExtensionCanvas>` (1.6)
+
+Makes a canvas inside a writable canvas, or at the top level if its write
+scope is the whole devlog. `type` is one of its own node types.
+
+Errors: `devlog.createCanvas: give it a title`; `No write access to that
+canvas`; `Only an extension that may write everywhere can make a top-level
+canvas`.
+
+#### `updateCanvas(canvasId, patch): Promise<ExtensionCanvas>` (1.6)
+
+Changes a writable canvas. `patch` may hold:
+
+| Key | Meaning |
+|---|---|
+| `title` | A new title. |
+| `parentId` | Move it: into another writable canvas, or `null` for the top level (only with write access everywhere). |
+| `type` | One of its own node types, or `null` for a plain canvas. It may not change a canvas that has another extension's type. |
+| `archived` | Archive or unarchive it, with everything beneath it. |
+
+Errors: `No write access to that canvas`; `No write access to where it would
+go`; `That canvas has another extension's type`.
+
+### Activity and ranges
+
+#### `activity(fromDate, toDate): Promise<ActivityRecord[]>` (1.7)
+
+What the app recorded between two local dates, inclusive: its own log
+(locks, idle, sleep, git events, corrections) merged with what extensions
+provide (time, focus).
+
+- Needs a read grant (throws `No read access` otherwise).
+- Events on canvases it may not read show `canvasId: null`; git events on
+  them are dropped.
+- `focus` events (window titles) only with read access to the **whole
+  devlog**.
+- At most 400 days per call; dates must be `YYYY-MM-DD` and in order.
+
+#### `range(fromDate, toDate): Promise<ExtensionDayBlocks[]>` (1.7)
+
+The day files with blocks written between two local dates, inclusive, on
+readable canvases (a day file is included when a block in it was written in
+the range, or a todo in it was ticked in the range). With no read grant,
+`[]`. Same date rules as `activity`.
+
+### Managed canvases
+
+#### `managedCanvas(key, opts?): Promise<ExtensionCanvas>` (1.7)
+
+A canvas this extension keeps: found by `key` (`^[a-z][a-z0-9_-]{0,63}$`),
+made on first use with `opts.title` (default: the key) at the top level. It
+carries `devlog.managed: <id>/<key>` in its `canvas.md`. On it the extension
+may, whatever it was granted:
+
+- read every block (`days`, `blocks`);
+- add blocks with kinds of its own and on any `date`;
+- `editBlock` any block.
+
+devlog-time keeps its **Timesheets** canvas this way.
+
+```js
+const log = await ctx.devlog.managedCanvas('deploys', { title: 'Deploys' })
+await ctx.devlog.addBlock(log.id, 'v2.3 → production', { kind: 'deploy', date: '2026-09-28' })
+```
+
+### Events
+
+#### `onBlockAdded(cb: (ev: BlockAddedEvent) => void): void` (1.6)
+
+Blocks posted **in the app** (by the user), as they are posted, on canvases
+it may read. Not called for blocks extensions add. Listeners get
+`{ canvasId, date, block }`.
+
+```js
+ctx.devlog.onBlockAdded(({ canvasId, block }) => {
+  if (/#deploy\b/.test(block.markdown)) void recordDeploy(canvasId, block)
+})
+```
+
+## `ctx.settings`
+
+Devlog-wide settings (`contributes.settings`), stored in `devlog.json`.
+Synchronous: the process keeps a copy.
+
+| Method | Since | Description |
+|---|---|---|
+| `get(key): string \| undefined` | 1.0 | The current value. All values are strings (`"true"` for a ticked checkbox). |
+| `onChange(cb: (settings: Record<string, string>) => void): void` | 1.0 | Called with every setting when the user saves. |
+
+## `ctx.secrets`
+
+Secrets kept on this machine, encrypted with the OS keychain (Electron
+`safeStorage`), never in the devlog. Keys are `^[a-z][a-z0-9_-]{0,63}$`.
+The user sets declared secrets on the extension's settings page; an
+extension may also set them itself (after an OAuth flow, say).
+
+| Method | Since | Description |
+|---|---|---|
+| `get(key): Promise<string \| undefined>` | 1.0 | |
+| `set(key, value): Promise<void>` | 1.0 | |
+| `delete(key): Promise<void>` | 1.0 | |
+
+## `ctx.files`
+
+Two private folders, reached only through relative paths:
+
+| Folder | Where | Synced | For |
+|---|---|---|---|
+| `ctx.files.repo` | `extensions/<id>/` in the devlog | yes, with the next commit | Data every machine should see: logs, ledgers of what was sent |
+| `ctx.files.local` | `userData/extension-data/<id>/<devlog>/` | no | Machine-only state: cursors, caches, preferences |
+
+Both implement `ExtensionFiles`:
+
+| Method | Description |
+|---|---|
+| `read(path): Promise<Uint8Array \| undefined>` | Bytes, or `undefined` if missing. |
+| `readText(path): Promise<string \| undefined>` | UTF-8 text, or `undefined`. |
+| `write(path, data: string \| Uint8Array): Promise<void>` | Replace a file atomically (temp file, then rename). Folders are made as needed. |
+| `append(path, text): Promise<void>` | Append text. Pair with `appendOnly` in the manifest for synced logs. |
+| `list(dir?): Promise<ExtensionFileInfo[]>` | Files under a folder (the whole folder by default). |
+| `stat(path): Promise<ExtensionFileInfo \| undefined>` | `{ path, size, mtime }`, or `undefined`. |
+| `remove(path): Promise<void>` | Delete a file. |
+
+Path rules: relative, `/`-separated, at most 400 characters; no absolute
+paths, drive letters, `.` or `..` segments, backslashes, `< > : " | ? *` or
+control characters, Windows device names (`con`, `nul`, `com1`, …), segments
+ending in `.` or space, or segments over 128 characters. Symlinks anywhere on
+the way are refused. Limits: **16 MB per file, 256 MB per folder, 20 000
+files**.
+
+The core ignores `extensions/` when listing, indexing and searching. Writes
+there don't count as unsaved work and don't trigger the commit debounce; they
+ride along with the next interval commit.
+
+```js
+await ctx.files.repo.append(`${ctx.machine}/2026/09/2026-09-28.jsonl`, JSON.stringify({ t: new Date().toISOString(), ok: true }) + '\n')
+const state = JSON.parse((await ctx.files.local.readText('state.json')) ?? '{}')
+```
+
+## `ctx.activity`
+
+The machine's state as the app sees it. See
+[Activity and Time Data](Activity-and-Time-Data).
+
+| Method | Since | Description |
+|---|---|---|
+| `on(cb: (n: ActivityNotice) => void): void` | 1.0 | `pause` (with `reason`: `locked`, `idle`, `suspended`) and `resume`, as they happen. |
+| `idleAfter(minutes): void` | 1.6 | Ask the app to count the machine idle after this many minutes without input (0: never; at most 1440). The app uses the shortest any extension asks for. *(no reply)* |
+
+## `ctx.ui`
+
+| Method | Since | Description |
+|---|---|---|
+| `notify(message): void` | 1.0 | A toast, prefixed with its display name; cut to 300 characters. *(no reply)* |
+| `confirm(message): Promise<boolean>` | 1.0 | A yes/no dialog titled with its display name; cut to 1000 characters. |
+| `pick(items: PickItem[], opts?: { placeholder? }): Promise<string \| null>` | 1.6 | A quick pick like the switcher. Returns the chosen item's `id`, or `null` if dismissed. Up to 5000 items; labels cut to 300, hints to 200 characters. |
+| `open({ canvasId, date?, blockId? }): void` | 1.6 | Show a canvas, or a block's page (`date` and `blockId` together). Throws `No access to that canvas` for a canvas it cannot see. *(no reply)* |
+| `openPage(viewId): void` | 1.7 | Show one of its `page` views. *(no reply)* |
+| `highlight(canvasId \| null): void` | 1.6 | Mark one canvas as its current one (the running task): the sidebar highlights it, and commits from a linked repository land on it when it is inside the linked canvas. `null` clears it. *(no reply)* |
+
+```js
+const id = await ctx.ui.pick(
+  [{ id: 'a', label: 'Staging', hint: 'eu-west' }, { id: 'b', label: 'Production' }],
+  { placeholder: 'Deploy to…' }
+)
+if (id && (await ctx.ui.confirm(`Deploy to ${id}?`))) ctx.ui.notify('Deploying')
+```
+
+## `ctx.app`
+
+The app around the window (1.6).
+
+| Method | Description |
+|---|---|
+| `setTrayLabel(label \| null): void` | Text beside the tray icon and in its tooltip (trimmed, at most 60 characters); `null` clears it. *(no reply)* |
+| `keepRunning(on: boolean): void` | Keep the app running in the tray when its window is closed, so the extension keeps going. *(no reply)* |
+
+## `ctx.commands`
+
+#### `register(id, run: (context: CommandContext) => unknown): void` (1.0, 1.6)
+
+Registers a command declared in `contributes.commands`. It appears in the
+quick switcher, and in the menus, keybindings and note box the manifest
+names.
+
+- `context` (1.6) says where it ran from (`source`: `switcher`,
+  `keybinding`, `menu`, `post`, `view`, `tray`) and on what: `canvasId` (the
+  canvas on screen, or the one whose menu it was) and, when the extension may
+  read that canvas, `date` and `blockId` (the block whose menu it was, the
+  block page on screen, or the block just posted). Canvases it cannot see are
+  left out.
+- A **string** it returns is shown to the user (first 500 characters); a
+  `check` command's result is shown on the settings page.
+- A thrown error is shown to the user.
+- Commands time out after 10 minutes.
+
+```js
+ctx.commands.register('copy-link', async ({ canvasId, date, blockId }) => {
+  if (!blockId) throw new Error('Run this on a block')
+  return `devlog block ${canvasId}/${date}/${blockId}`
+})
+```
+
+## `ctx.views`
+
+Views declared in `contributes.views` (1.5). See [Views and UI](Views-and-UI).
+
+| Method | Description |
+|---|---|
+| `handle(viewId, handler: (method: string, args: unknown[]) => unknown): void` | Answer calls from the view's page (`devlog.call(method, ...args)` in the page). The handler's return value (or thrown error) is the page's reply. 60-second timeout. Throws for a view not declared in the manifest. |
+| `post(viewId, message): void` | Send a message to every open copy of the view (the page's `devlog.onMessage` / `useMessages`). *(no reply)* |
+
+```js
+ctx.views.handle('status', async (method, args) => {
+  switch (method) {
+    case 'status': return clock.status()
+    case 'start': await clock.start(String(args[0])); return clock.status()
+    default: throw new Error(`No method ${method}`)
+  }
+})
+clock.onChange((st) => ctx.views.post('status', st))
+```
+
+## `ctx.destinations`
+
+Timesheet destinations. See [Timesheet Destinations](Timesheet-Destinations).
+
+| Method | Since | Description |
+|---|---|---|
+| `register(id, { preview, send }): void` | 1.3 | Register a destination declared in `contributes.destinations`. |
+| `list(): Promise<DestinationInfo[]>` | 1.7 | Destinations registered by running extensions (including its own). |
+| `preview(to: { extension, id }, sheet: SheetToSend): Promise<DestinationLine[]>` | 1.7 | What sending would do. Needs `permissions.send`. |
+| `send(to: { extension, id }, sheet: SheetToSend): Promise<SendResult>` | 1.7 | Send a **final** week. Needs `permissions.send`. |
+
+## `ctx.provide`
+
+Data the app draws in its own views (1.1). See
+[Activity and Time Data](Activity-and-Time-Data).
+
+| Method | Since | Description |
+|---|---|---|
+| `focus(fn: (fromDate, toDate) => Promise<FocusEvent[]>): void` | 1.1 | Window focus changes between two local dates (inclusive), for the timeline, review and summary. |
+| `activity(fn: (fromDate, toDate) => Promise<TimeEvent[]>): void` | 1.6 | Time-tracking events (`start`, `task`, `stop`, `heartbeat`), for the review, summary, timeline and timesheet. While any extension provides time, the app also logs lock/idle/sleep and git events. |
+
+Providers must answer within 20 seconds; at most 500 000 events per call are
+used.
+
+## Timeouts and limits
+
+| What | Limit |
+|---|---|
+| `activate` | 30 s, or the extension is stopped as failed |
+| A command | 10 min |
+| A view call | 60 s |
+| Destination preview / send | 2 min / 10 min |
+| Focus / activity provider | 20 s |
+| Event delivery (`onBlockAdded`, `activity.on`) | 10 s per listener round |
+| Process heap | 256 MB |
+| Block text | 100 000 characters |
+| Metadata value | 500 characters, one line |
+| Files | 16 MB per file, 256 MB and 20 000 files per folder |
+| `activity` / `range` | 400 days per call |
+| Command result shown | 500 characters |
diff --git a/wiki/Extension-Host-Protocol.md b/wiki/Extension-Host-Protocol.md
new file mode 100644
index 0000000..aa6607a
--- /dev/null
+++ b/wiki/Extension-Host-Protocol.md
@@ -0,0 +1,112 @@
+# Extension host protocol
+
+How the app runs an extension and talks to it. Extension authors never deal
+with this directly (`ctx` hides it); it matters when working on Devlog
+itself, or when debugging an extension that will not start.
+
+Types: [`packages/extension-api/src/protocol.ts`](https://github.com/sdeken/devlog/blob/main/packages/extension-api/src/protocol.ts).
+Implementation: `src/main/extensions/host.ts` (the app side),
+`src/main/extensions/hostProcess.ts` (inside the process),
+`src/main/extensions/manager.ts` (the API, consent and grants).
+
+## Starting the process
+
+`ExtensionHost.start()` forks the host script (`out/main/extensionHost.js`,
+copied into user data as `extension-host/host-<hash>.js`, outside any archive) with:
+
+| Setting | Sandboxed | Unrestricted (trusted) |
+|---|---|---|
+| Executable | The app binary with `ELECTRON_RUN_AS_NODE=1` | same |
+| `execArgv` | `--permission --allow-fs-read=<host script>` and `--max-old-space-size=256` | `--max-old-space-size=256` only |
+| Environment | `ELECTRON_RUN_AS_NODE` plus `SystemRoot`, `windir`, `TZ`, `LANG`, `LC_ALL` if set | The app's full environment |
+| `packageDir` | `null` | The unpacked folder |
+| Serialisation | `advanced` (structured clone) over Node IPC | same |
+| stdout / stderr | Piped to the app's, each line prefixed `[ext <id>]` | same |
+
+Electron's `utilityProcess` ignores `--permission`, which is why this is a
+plain Node child; the build keeps Electron's `RunAsNode` fuse on.
+
+## Messages
+
+App → extension (`ToExtension`):
+
+| `t` | Fields | Meaning |
+|---|---|---|
+| `init` | `id`, `apiVersion`, `machine`, `packageDir`, `code`, `filename`, `settings` | Sent once. `code` is the bundle's source. |
+| `call` | `id`, `method`, `args` | Run something in the extension (below). |
+| `res` | `id`, `ok`, `value?`, `error?` | The answer to one of the extension's calls. |
+| `settings` | `settings` | The devlog-wide settings changed. |
+| `stop` | — | Run `deactivate()` if exported, then exit. |
+
+Extension → app (`FromExtension`):
+
+| `t` | Fields | Meaning |
+|---|---|---|
+| `ready` | `commands` | `activate` returned; the ids of commands registered so far. |
+| `failed` | `error` | Evaluating the bundle or `activate` threw (the process then exits). |
+| `call` | `id`, `method`, `args` | An API request (`APP_METHODS`). |
+| `res` | `id`, `ok`, `value?`, `error?` | The answer to an app call. |
+| `registered` | `command` | A command registered after `ready`. |
+
+## Startup sequence
+
+1. The app forks the process and sends `init`.
+2. The process compiles `code` with `vm.compileFunction` as a CommonJS module
+   (`exports`, `require`, `module`, `__filename`, `__dirname`). `require`
+   resolves Node built-ins only.
+3. It takes `activate` from `module.exports` (or `module.exports.default`)
+   and calls it with a `DevlogContext` built from the init message.
+4. When `activate` resolves, it sends `ready`. If that takes more than 30
+   seconds the app stops the process as failed.
+
+## Methods the extension calls (`APP_METHODS`)
+
+Every `ctx` call becomes one of these, answered by `res`:
+
+| Group | Methods |
+|---|---|
+| devlog | `devlog.canvases`, `field`, `days`, `blocks`, `search`, `addBlock`, `todos`, `createCanvas`, `updateCanvas`, `editBlock`, `promote`, `subscribe` (for `onBlockAdded`), `activity`, `range`, `managedCanvas` |
+| destinations | `destinations.list`, `preview`, `send`, and `destination.register` |
+| secrets | `secrets.get`, `set`, `delete` |
+| files | `files.read`, `write`, `append`, `list`, `stat`, `remove` (first argument: `'repo'` or `'local'`) |
+| activity | `activity.subscribe` (for `activity.on`), `activity.idleAfter` |
+| ui | `ui.notify`, `confirm`, `pick`, `open`, `openPage`, `highlight` |
+| app | `app.trayLabel`, `app.keepRunning` |
+| registration | `provide.register` (`'focus'` or `'activity'`), `views.handle`, `views.post` |
+
+`ctx.settings.get` never crosses the channel: the process keeps the last
+settings it was sent. Registration methods tell the app what to route to the
+extension; the handlers themselves stay in the process.
+
+## Methods the app calls (`ExtensionSideMethod`)
+
+| Method | Args | Timeout | Answer |
+|---|---|---|---|
+| `command.run` | `[commandId, context]` | 10 min | The command's return value (a string is shown, first 500 characters) |
+| `activity.notice` | `[ActivityNotice]` | 10 s | — |
+| `block.added` | `[BlockAddedEvent]` | 10 s | — |
+| `provide.focus` | `[from, to]` | 20 s | `FocusEvent[]` |
+| `provide.activity` | `[from, to]` | 20 s | `TimeEvent[]` |
+| `destination.preview` | `[destinationId, DestinationSheet]` | 2 min | `DestinationLine[]` |
+| `destination.send` | `[destinationId, DestinationSheet]` | 10 min | `SendResult` |
+| `view.call` | `[viewId, method, args]` | 60 s | The handler's return value |
+
+Answers are validated and trimmed by the manager before they reach the app's
+views (unknown event types dropped, strings cut to length, at most 500 000
+events).
+
+## Where the grant is enforced
+
+Always on the app side, in `ExtensionManager.handle`: every `devlog.*` call
+checks the canvas against the read or write scope (`scopeCanvasIds`,
+`visibleCanvases` from `packages/core/src/extensions.ts`), outgoing events
+and command contexts are filtered the same way, and `files.*` goes through an
+`ExtensionFileStore` rooted at the extension's own folders. Nothing the
+process sends can widen what it sees.
+
+## Lifecycle states
+
+`ExtensionHost.state` is `starting`, `running`, `failed` or `stopped`, with
+`error` holding the reason for a failure. The Extensions page shows it.
+A process that exits unexpectedly is marked failed (`Stopped unexpectedly (…)`)
+and its pending calls are rejected with `The extension stopped`.
diff --git a/wiki/Extension-Manifest.md b/wiki/Extension-Manifest.md
new file mode 100644
index 0000000..8ffdf61
--- /dev/null
+++ b/wiki/Extension-Manifest.md
@@ -0,0 +1,193 @@
+# Extension manifest
+
+Every extension has a `devlog-extension.json` at the top of its folder. The
+app reads it **without running any code**: canvas fields, settings, commands,
+views and node types show up from the manifest alone, and the consent dialog
+shows its permissions. The parser is `parseExtensionManifest` in
+[`packages/core/src/extensions.ts`](https://github.com/sdeken/devlog/blob/main/packages/core/src/extensions.ts);
+it reports every problem at once (`Invalid extension manifest: …; …`).
+
+## Complete example
+
+```jsonc
+{
+  "name": "devlog-jira",
+  "displayName": "Jira worklogs",
+  "version": "1.2.0",
+  "description": "Sends timesheet entries to Jira as worklogs.",
+  "api": "^1.3.0",
+  "main": "main.js",
+  "contributes": {
+    "canvasFields": [
+      { "key": "issue", "label": "Jira issue", "placeholder": "ACME-123" }
+    ],
+    "settings": [
+      { "key": "baseurl", "label": "Jira address", "type": "url", "required": true },
+      { "key": "email", "label": "Account email", "type": "email" }
+    ],
+    "secrets": [
+      { "key": "token", "label": "API token", "required": true }
+    ],
+    "commands": [
+      { "id": "check", "label": "Check the Jira connection" }
+    ],
+    "check": "check",
+    "destinations": [
+      { "id": "worklogs", "label": "Jira" }
+    ],
+    "views": [],
+    "nodeTypes": []
+  },
+  "permissions": {
+    "read": false,
+    "write": false,
+    "network": ["*.atlassian.net"]
+  },
+  "appendOnly": ["sent/*.jsonl"]
+}
+```
+
+## Top-level fields
+
+| Field | Type | Required | Rules and meaning |
+|---|---|---|---|
+| `name` | string | yes | `^[a-z0-9][a-z0-9._-]{0,63}$`. Informational: the **id** comes from the source, not from this. |
+| `displayName` | string | no | Shown everywhere in the app. Defaults to `name`. |
+| `version` | string | yes | `1.2.3` or `1.2.3-pre` (a leading `v` is accepted). |
+| `description` | string | no | Shown on the extension's card and in the consent dialog. |
+| `api` | string | yes | The extension API range it was built for, e.g. `^1.6.0`. Declare the **lowest** you need; newer apps keep loading it. |
+| `main` | string | no | The bundled entry file, a relative path inside the extension (no `..`, no backslashes). An extension with no code (fields only) can omit it. |
+| `contributes` | object | no | What the app shows without running it (below). |
+| `permissions` | object | no | What it asks for (below). |
+| `appendOnly` | string[] | no | Globs within its repo folder (`extensions/<id>/`) that git should union-merge. |
+
+## `contributes`
+
+### Fields: `canvasFields`, `settings`, `secrets`
+
+All three are lists of fields:
+
+| Property | Type | Applies to | Meaning |
+|---|---|---|---|
+| `key` | string | all | `^[a-z][a-z0-9_-]{0,63}$`, unique within its list. |
+| `label` | string | all | Shown beside the input. Defaults to `key`. |
+| `placeholder` | string | all | Placeholder text. |
+| `description` | string | all | A sentence or two under the field. |
+| `type` | string | settings, canvas fields | `text` (default), `url`, `email`, `number`, `select`, `checkbox`, `textarea`. Secrets are always hidden text. |
+| `options` | `{ value, label }[]` | `select` | Required for `select` (a select without options is an error). |
+| `required` | boolean | settings, secrets | The extension's card says "Needs: …" until it is set. |
+| `inherited` | `false` | canvas fields | (1.7) The field applies to its canvas only; canvases inside it do not take it on. |
+
+Validation when saved (`fieldProblem`): `url` must start with `http://` or
+`https://`; `email` must look like one; `number` must parse; `select` must be
+one of the options; `checkbox` is the string `true` or `false`. Every value is
+a **string**.
+
+Where they are stored:
+
+| List | Stored in | Read with |
+|---|---|---|
+| `settings` | `devlog.json` → `settings.<id>.<key>` (synced) | `ctx.settings.get(key)` |
+| `secrets` | user data, encrypted with the OS keychain (per machine) | `await ctx.secrets.get(key)` |
+| `canvasFields` | the canvas's `canvas.md` as `ext.<id>.<key>: value` | `await ctx.devlog.field(canvasId, key)` or `canvas.fields[key]` |
+
+Canvas fields show as a page per extension in the canvas's Properties.
+Unless `inherited: false`, a canvas without its own value takes the nearest
+ancestor's (that is what `devlog.field` returns; `ExtensionCanvas.fields`
+holds only the values set on that canvas).
+
+### `check`
+
+The id of one of its commands that tests the settings (a login, say). The
+settings page offers **Test** and **Save and test** and shows the string the
+command returns, or its error. It must name a declared command.
+
+### `commands`
+
+| Property | Type | Since | Meaning |
+|---|---|---|---|
+| `id` | string | 1.0 | `^[a-z][a-z0-9_-]{0,63}$`. Register it in code with `ctx.commands.register(id, run)`. |
+| `label` | string | 1.0 | Shown in the quick switcher and menus. |
+| `keybinding` | string | 1.6 | e.g. `Mod+Shift+S`. See below. |
+| `menus` | string[] | 1.6 | Any of `canvas` (a canvas's right-click menu), `block` (a block's actions), `tray` (the tray icon's menu). |
+| `nodeType` | string | 1.6 | Offer it only on canvases of this node type: a type id of its own (`task`) or a full name (`builtin.devlog-time/task`). |
+| `post` | boolean | 1.6 | Make it a way to post from the note box: its keybinding posts the note, then runs the command on the new block (`context.source === 'post'`). |
+| `tag` | string | 1.6 | With `post: true`: `#<tag>` on the first line of a note also posts this way; the tag is taken off before posting. |
+
+**Keybindings** are normalised to one spelling: modifiers in the order `Mod`,
+`Ctrl`, `Alt`, `Shift`, then one key. `Mod` is Ctrl, or Cmd on a Mac
+(`CmdOrCtrl` is accepted as a synonym, as are `Control` and `Option`). The key
+is a letter or digit, a punctuation mark (`` ` - = [ ] \ ; ' , . / + ``),
+`F1`–`F24`, or one of `Enter Space Escape Tab Backspace Delete Home End PageUp
+PageDown ArrowUp ArrowDown ArrowLeft ArrowRight`. A plain key or Shift+key is
+refused (it would steal typing), except F-keys. `Mod++` means the plus key.
+
+### `views` (1.5)
+
+Pages from the package that the app shows in sandboxed frames.
+
+| Property | Type | Meaning |
+|---|---|---|
+| `id` | string | `^[a-z][a-z0-9_-]{0,63}$`, unique. Answer its calls with `ctx.views.handle(id, …)`. |
+| `title` | string | Shown in the sidebar, switcher or tooltip. Defaults to `id`. |
+| `entry` | string | An `.html` file, relative to the extension folder. |
+| `placement` | string | `page`, `statusbar`, `popover` or `canvasHeader` (1.6). |
+| `icon` | string | One character or emoji (at most two code points), for the sidebar. |
+| `nodeType` | string | (1.6) For `canvasHeader`: show only on canvases of this type. |
+
+See [Views and UI](Views-and-UI) for what each placement does.
+
+### `nodeTypes` (1.6)
+
+Kinds of canvas the extension gives meaning to.
+
+| Property | Type | Meaning |
+|---|---|---|
+| `id` | string | `^[a-z][a-z0-9_-]{0,63}$`, unique. The full name is `<extension id>/<id>`. |
+| `label` | string | e.g. "Task" (at most 40 characters). Offered as **New *label* inside…** and under **Type** in canvas properties. |
+| `icon` | string | One character or emoji, shown before the canvas's name. |
+| `placeholder` | string | Added to the note box's placeholder on canvases of this type (at most 120 characters). |
+
+### `destinations` (1.3)
+
+Places a finished timesheet can be sent. Each is `{ "id", "label" }` and must
+be registered in code with `ctx.destinations.register(id, { preview, send })`.
+See [Timesheet Destinations](Timesheet-Destinations).
+
+## `permissions`
+
+| Permission | Type | Meaning |
+|---|---|---|
+| `read` | boolean | Wants to read blocks. The user picks the scope: the whole devlog or chosen canvases. |
+| `write` | boolean | Wants to add blocks and change canvases. The user picks the scope. |
+| `network` | string[] | Domains it talks to (`example.com`, `*.atlassian.net`, optionally with `:port`). **Shown at consent, not enforced.** |
+| `send` | boolean | (1.7) Sends finished timesheets through *other* extensions' destinations. |
+| `unrestricted` | boolean | Runs without the sandbox: full file-system and process access. Runs only if the user ticks "I trust it". |
+
+Without `read` an extension still gets its own settings, secrets, files and
+the canvas fields it declared, and can list the canvases in its write scope.
+See [Sandbox and Permissions](Sandbox-and-Permissions).
+
+## `appendOnly`
+
+Globs (`^[A-Za-z0-9_.*/{}-]{1,128}$`, relative, no `..`) within the
+extension's repo folder. The app writes a `merge=union` line for each into
+the devlog's `.gitattributes`, so two machines appending to the same file
+never conflict. Use it for JSON-lines logs you only ever append to:
+
+```json
+"appendOnly": ["**/*.jsonl"]
+```
+
+## Common manifest errors
+
+| Message | Fix |
+|---|---|
+| `"name" must be lowercase letters, digits, "." , "_" or "-"` | Rename; no capitals or spaces. |
+| `"api" is not a version range: …` | Use `^1.6.0`, `~1.7.0`, `1.x`, … |
+| `"contributes.settings": key "BaseURL" must be lowercase …` | Keys are lowercase. |
+| `… is a select with no options` | Add `options`. |
+| `… has keybinding "Shift+S"; use something like "Mod+Shift+S"` | Add `Mod`, `Ctrl` or `Alt`. |
+| `"contributes.views": x needs an "entry" .html file inside the extension` | `entry` must end in `.html` and be relative. |
+| `"contributes.check" must name one of its commands` | Declare the command too. |
+| `"tag" is a lowercase word, on a "post" command` | Add `"post": true`. |
diff --git a/wiki/Extension-Quickstart.md b/wiki/Extension-Quickstart.md
new file mode 100644
index 0000000..35549f4
--- /dev/null
+++ b/wiki/Extension-Quickstart.md
@@ -0,0 +1,218 @@
+# Extension quickstart
+
+This page builds **Standup**, a small extension that posts yesterday's and
+today's work as one block on the canvas you are looking at. On the way it uses
+a manifest, a command with a keybinding, a setting, the read and write API,
+a private file, a unit test, the development override and a release.
+
+Read [Extensions Overview](Extensions-Overview) first if you have not.
+
+## 1. Lay out the project
+
+```
+devlog-standup/
+├── devlog-extension.json
+├── package.json
+├── src/
+│   └── main.ts
+└── tests/
+    └── main.test.ts
+```
+
+The shipped extension is only `devlog-extension.json` and the bundled
+`main.js`; `src/`, `tests/` and `node_modules/` stay out of the zip.
+
+### Types
+
+`@devlog/extension-api` is not published to npm. Take it from a checkout of
+the Devlog repository, for example:
+
+```sh
+git clone https://github.com/sdeken/devlog ../devlog
+npm install --save-dev ../devlog/packages/extension-api esbuild typescript vitest
+```
+
+It exports TypeScript sources (`@devlog/extension-api`,
+`@devlog/extension-api/testing`, `/view`, `/protocol`), so use
+`"moduleResolution": "bundler"` in your `tsconfig.json`. The types are for
+building only; nothing from the package is needed at runtime, because the app
+provides `ctx`.
+
+## 2. Write the manifest
+
+`devlog-extension.json`:
+
+```json
+{
+  "name": "devlog-standup",
+  "displayName": "Standup",
+  "version": "0.1.0",
+  "description": "Posts what you wrote yesterday and today as one block.",
+  "api": "^1.7.0",
+  "main": "main.js",
+  "contributes": {
+    "settings": [
+      {
+        "key": "heading",
+        "label": "Heading",
+        "placeholder": "Standup",
+        "description": "The first line of the block it posts."
+      }
+    ],
+    "commands": [
+      { "id": "post", "label": "Post a standup here", "keybinding": "Mod+Alt+U", "menus": ["canvas"] }
+    ]
+  },
+  "permissions": { "read": true, "write": true }
+}
+```
+
+- `api` is the lowest API version you need, as a range. `^1.7.0` because
+  `devlog.range` arrived in 1.7.
+- Commands must be declared here *and* registered in code.
+- `read` and `write` make the consent dialog ask the user for a scope.
+
+Every field is described in [Extension Manifest](Extension-Manifest).
+
+## 3. Write the code
+
+`src/main.ts`:
+
+```ts
+import type { CommandContext, DevlogContext } from '@devlog/extension-api'
+
+/** Local calendar date, YYYY-MM-DD. */
+const day = (d: Date): string =>
+  `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+
+export async function activate(ctx: DevlogContext): Promise<void> {
+  ctx.commands.register('post', async (context: CommandContext) => {
+    if (!context.canvasId) throw new Error('Open a canvas first')
+
+    const today = new Date()
+    const yesterday = new Date(today.getTime() - 86_400_000)
+    const names = new Map((await ctx.devlog.canvases()).map((c) => [c.id, c.title]))
+
+    // Every day file with blocks written in the range, on canvases it may read.
+    const lines: string[] = []
+    for (const { canvasId, blocks } of await ctx.devlog.range(day(yesterday), day(today))) {
+      for (const b of blocks) {
+        if (b.meta?.ext === ctx.id) continue // skip our own standups
+        const first = b.markdown.split('\n')[0].slice(0, 120)
+        lines.push(`- **${names.get(canvasId) ?? canvasId}**: ${first}`)
+      }
+    }
+    if (!lines.length) return 'Nothing written yesterday or today'
+
+    const heading = ctx.settings.get('heading') || 'Standup'
+    await ctx.devlog.addBlock(context.canvasId, `**${heading}**\n\n${lines.join('\n')}`, { meta: { source: 'standup' } })
+
+    // Remember when we last posted, on this machine only.
+    await ctx.files.local.write('last.json', JSON.stringify({ at: today.toISOString(), count: lines.length }))
+    return `Posted ${lines.length} lines`
+  })
+}
+```
+
+What to notice:
+
+- `activate` only **registers** things. The app waits for it to return (30
+  seconds at most) before it counts the extension as running.
+- `context.canvasId` is the canvas on screen (or the canvas whose menu was
+  used). Canvases outside the grant are left out.
+- `range` and `canvases` return only what the grant allows. `addBlock` fails
+  with `No write access to that canvas` outside the write scope.
+- Throwing from a command shows the error to the user; returning a string
+  shows the string.
+- The block it adds is marked `ext=<id>` and is read-only in the app.
+
+## 4. Bundle it
+
+```sh
+npx esbuild src/main.ts --bundle --platform=node --format=cjs --target=node20 --outfile=main.js
+```
+
+The result must be one CommonJS file. `require` of anything but a Node
+built-in fails at runtime ("Extensions are bundled"), so bundle every
+dependency. `fetch` is available.
+
+## 5. Test it without Devlog
+
+`tests/main.test.ts`:
+
+```ts
+import { describe, expect, it } from 'vitest'
+import { createTestContext, type TestCanvas } from '@devlog/extension-api/testing'
+import { activate } from '../src/main'
+
+const now = new Date()
+const today = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`
+const acme: TestCanvas = {
+  id: 'acme', title: 'Acme', parentId: null, task: false, archived: false, fields: {},
+  days: { [today]: [{ id: 'b1', createdAt: now.toISOString(), markdown: 'Fixed the login bug' }] }
+}
+const notes: TestCanvas = { id: 'notes', title: 'Notes', parentId: null, task: false, archived: false, fields: {} }
+
+describe('standup', () => {
+  it('posts what was written', async () => {
+    const t = createTestContext({ settings: { heading: 'Daily' }, canvases: [structuredClone(acme), structuredClone(notes)] })
+    await activate(t.ctx)
+    expect(await t.run('post', { canvasId: 'notes' })).toBe('Posted 1 lines')
+    expect(t.added[0].block.markdown).toContain('**Acme**: Fixed the login bug')
+  })
+
+  it('cannot write outside its grant', async () => {
+    const t = createTestContext({ write: [], canvases: [structuredClone(acme), structuredClone(notes)] })
+    await activate(t.ctx)
+    await expect(t.run('post', { canvasId: 'notes' })).rejects.toThrow('No write access')
+  })
+})
+```
+
+The harness follows the real rules (relative paths only, grants enforced,
+blocks marked as yours) and adds blocks to the canvases you pass in, so give
+each test its own copy. See [Testing Extensions](Testing-Extensions).
+
+## 6. Run it in Devlog
+
+Point Devlog at your folder without releasing anything. In the app's **user
+data folder** create `extension-dev.json`, mapping a `devlog.json` key to your
+folder:
+
+```json
+{ "devlog-standup": "/home/me/src/devlog-standup" }
+```
+
+The user data folder is typically `%APPDATA%\Devlog` (Windows),
+`~/Library/Application Support/Devlog` (macOS) or `~/.config/Devlog`
+(Linux); `devlog` rather than `Devlog` when running from source; or whatever
+`DEVLOG_USER_DATA` points to.
+
+Then in **Extensions** add `devlog-standup` with version `builtin`. The
+folder is used as is (its id is `builtin.devlog-standup`). Every change to
+the folder is new code, so it asks for consent again; rebuild, then allow.
+
+The extension's `console.log` and `console.error` output goes to the app's
+stdout/stderr, prefixed `[ext <id>]`, so run the app from a terminal
+(`npm run dev` in a Devlog checkout) to see it.
+
+## 7. Release it
+
+1. Zip the folder's shipped files (the manifest at the top of the zip, or
+   inside one folder) as `<anything>.devlog-ext.zip`.
+2. Create a GitHub release tagged with the version (`v0.1.0`) and attach the
+   zip.
+3. Users add `your-name/devlog-standup` with a range such as `^0.1.0`.
+   Devlog picks the newest matching release, pins its SHA-256 in
+   `devlog.lock.json`, and asks before running it.
+
+Private repositories work: users add a GitHub token on the Extensions page.
+Alternatively host the zip anywhere over HTTPS and add it by URL.
+
+## Next steps
+
+- Add a status bar item or a page: [Views and UI](Views-and-UI).
+- Send timesheets somewhere: [Timesheet Destinations](Timesheet-Destinations).
+- React to posts: `ctx.devlog.onBlockAdded` in the
+  [API reference](Extension-API-Reference#events).
+- Read a real one: [Built-in Extensions](Built-in-Extensions).
diff --git a/wiki/Extension-Types.md b/wiki/Extension-Types.md
new file mode 100644
index 0000000..48592aa
--- /dev/null
+++ b/wiki/Extension-Types.md
@@ -0,0 +1,356 @@
+# Extension types
+
+Every type an extension sees, from
+[`packages/extension-api/src/index.ts`](https://github.com/sdeken/devlog/blob/main/packages/extension-api/src/index.ts)
+(`@devlog/extension-api`) and
+[`view.ts`](https://github.com/sdeken/devlog/blob/main/packages/extension-api/src/view.ts)
+(`@devlog/extension-api/view`). All of them are plain data; times are ISO-8601
+strings and dates are local `YYYY-MM-DD`.
+
+```ts
+import type { DevlogContext, ExtensionCanvas, ExtensionBlock } from '@devlog/extension-api'
+import { API_VERSION } from '@devlog/extension-api' // '1.7.0'
+```
+
+## Canvases and blocks
+
+### `ExtensionCanvas`
+
+```ts
+interface ExtensionCanvas {
+  id: string
+  title: string
+  parentId: string | null
+  task: boolean
+  type?: string                       // (1.6) "<extension id>/<type id>"
+  archived: boolean
+  fields: Record<string, string>      // this extension's own canvas fields set on this canvas
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `id` | Stable random id; renames and moves keep it. |
+| `parentId` | The enclosing canvas, or `null` at the top level. |
+| `task` | Whether it is devlog-time's task type (same as `type === 'builtin.devlog-time/task'`). |
+| `type` | Its node type, if any. |
+| `fields` | Keys as declared in `contributes.canvasFields`, values set **on this canvas** only (use `devlog.field` for the inherited value). |
+
+### `ExtensionBlock`
+
+```ts
+interface ExtensionBlock {
+  id: string
+  createdAt: string
+  updatedAt?: string
+  markdown: string
+  parentId?: string
+  kind?: string
+  hidden?: boolean
+  meta?: Record<string, string>
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `id` | Unique within its day file. |
+| `createdAt` / `updatedAt` | When written, and last edited. |
+| `markdown` | The text. Image sources are repo-root-relative (`canvases/k3/k3m9x2q7vd/entries/2026/09/assets/x.png`). |
+| `parentId` | The block it sits inside, if any. |
+| `kind` | Absent for a note; else `commit`, `task`, `todo`, `done`, `timesheet`, or an extension's own kind on a canvas it keeps. |
+| `hidden` | Collapsed in the stream (still there, still searchable). |
+| `meta` | Attributes: `ext` (the extension that wrote it), `canvas` (a task block's canvas), `done` (when a todo was ticked), `repo`/`hash`/`branch`/`author` (commits), and whatever an extension set. |
+
+### `ExtensionTodo` (1.4)
+
+```ts
+interface ExtensionTodo {
+  canvasId: string
+  date: string                               // the day file it lives in
+  block: ExtensionBlock                      // kind: 'todo'; meta.done once ticked
+  trail: Array<{ id: string; title: string }> // blocks it sits inside, outermost first
+}
+```
+
+### `ExtensionDayBlocks` (1.7)
+
+```ts
+interface ExtensionDayBlocks { canvasId: string; date: string; blocks: ExtensionBlock[] }
+```
+
+### `ExtensionSearchResult`
+
+```ts
+interface ExtensionSearchResult {
+  blocks: Array<{ canvasId: string; date: string; block: ExtensionBlock }>
+}
+```
+
+## Inputs
+
+### `AddBlockOptions` (1.4, 1.7)
+
+```ts
+interface AddBlockOptions {
+  meta?: Record<string, string>
+  parentId?: string   // add inside this block (needs date)
+  date?: string       // the parent's day file; or, on a kept canvas, any day
+  todo?: boolean      // add as a todo
+  kind?: string       // on a kept canvas: its own kind
+}
+```
+
+### `NewCanvas` (1.6)
+
+```ts
+interface NewCanvas { title: string; parentId?: string | null; type?: string }
+```
+
+### `CanvasPatch` (1.6)
+
+```ts
+interface CanvasPatch {
+  title?: string
+  parentId?: string | null
+  type?: string | null     // one of its own types, or null for a plain canvas
+  archived?: boolean
+}
+```
+
+### `PickItem` (1.6)
+
+```ts
+interface PickItem { id: string; label: string; hint?: string }
+```
+
+## Commands and events
+
+### `CommandContext` (1.6)
+
+```ts
+interface CommandContext {
+  source: 'switcher' | 'keybinding' | 'menu' | 'post' | 'view' | 'tray'
+  canvasId?: string   // the canvas on screen, or the one whose menu it was
+  date?: string       // with blockId: the block's day file
+  blockId?: string    // the block whose menu it was, the page on screen, or the block just posted
+}
+```
+
+`date` and `blockId` are given only when the extension may read `canvasId`.
+
+### `BlockAddedEvent` (1.6)
+
+```ts
+interface BlockAddedEvent { canvasId: string; date: string; block: ExtensionBlock }
+```
+
+### `ActivityNotice`
+
+```ts
+interface ActivityNotice {
+  t: string
+  type: 'pause' | 'resume' | 'task'
+  reason?: 'locked' | 'idle' | 'suspended'
+  canvasId?: string | null
+}
+```
+
+`task` notices came from the app's own tracker before 1.6 and are no longer
+sent now that time tracking is an extension.
+
+## Activity and time
+
+### `ActivityRecord` (1.7)
+
+What `devlog.activity` returns.
+
+```ts
+interface ActivityRecord {
+  t: string
+  type: 'start' | 'stop' | 'heartbeat' | 'lock' | 'unlock' | 'idle' | 'active'
+      | 'suspend' | 'resume' | 'task' | 'focus' | 'git' | 'exclude'
+  canvasId?: string | null
+  entryId?: string
+  app?: string; title?: string                                   // focus
+  repo?: string; action?: string; branch?: string; from?: string; detail?: string // git
+  start?: string; end?: string; id?: string; cancels?: string     // exclude
+  machine?: string
+}
+```
+
+| `type` | Meaning |
+|---|---|
+| `start` / `stop` | The clock started or stopped with the app (from a time provider). |
+| `task` | The active task changed (`canvasId`, or `null`: stopped). |
+| `heartbeat` | Still running (the app counts time up to the last one when a log just ends). |
+| `lock` / `unlock` | Screen locked / unlocked. |
+| `idle` / `active` | No input for the idle threshold / input again. |
+| `suspend` / `resume` | Sleep / wake. |
+| `focus` | The window in front changed (`app`, `title`). |
+| `git` | Something in a linked repository: `action` is `commit`, `branch`, `checkout`, `push`, `merge`, `rebase`, `pull`, `stash` or `reset`. |
+| `exclude` | A correction: no task time between `start` and `end`; or undoes the exclusion whose id is `cancels`. |
+
+### `TimeEvent` (1.6)
+
+What a time provider returns.
+
+```ts
+interface TimeEvent {
+  t: string
+  type: 'start' | 'task' | 'stop' | 'heartbeat'
+  canvasId?: string | null   // for task (and start): the active canvas
+  blockId?: string           // the block that started it, if one did
+  machine: string            // ctx.machine where it was recorded
+}
+```
+
+### `FocusEvent` (1.1)
+
+What a focus provider returns.
+
+```ts
+interface FocusEvent { t: string; app: string; title: string; machine: string }
+```
+
+## Destinations
+
+### `DestinationSheet` (1.3)
+
+What a destination receives.
+
+```ts
+interface DestinationSheet {
+  week: string                // the Monday, YYYY-MM-DD
+  status: 'draft' | 'final'
+  entries: DestinationEntry[]
+}
+```
+
+### `DestinationEntry` (1.3)
+
+```ts
+interface DestinationEntry {
+  id: string                    // stable within the week's timesheet
+  date: string
+  start: string                 // ISO, on a local quarter hour
+  minutes: number               // a multiple of 15
+  note?: string
+  canvasId: string
+  task: string                  // "Client / Project / Task"
+  client: string                // the top-level canvas's title
+  fields: Record<string, string> // this extension's canvas fields, inherited
+}
+```
+
+### `DestinationLine` (1.3)
+
+One line of what a destination would do.
+
+```ts
+interface DestinationLine {
+  id: string
+  entryIds: string[]      // the timesheet entries it covers
+  date: string
+  start?: string
+  minutes: number
+  target: string          // an issue key, an assignment…
+  description?: string
+  action: 'create' | 'update' | 'delete' | 'unchanged' | 'skip'
+  reason?: string         // why, for skip
+}
+```
+
+### `SendResult` (1.3)
+
+```ts
+interface SendResult {
+  done: string[]                                  // line ids that went through
+  failed: Array<{ lineId: string; error: string }>
+  summary: string                                 // "3 worklogs created, 1 updated"
+}
+```
+
+### `Destination` (1.3)
+
+```ts
+interface Destination {
+  preview(sheet: DestinationSheet): Promise<DestinationLine[]>
+  send(sheet: DestinationSheet): Promise<SendResult>
+}
+```
+
+### `DestinationInfo` (1.7)
+
+```ts
+interface DestinationInfo {
+  extension: string   // the extension's devlog.json key
+  from: string        // its display name
+  id: string
+  label: string
+}
+```
+
+### `SheetToSend` (1.7)
+
+What a sender passes to `destinations.preview` / `send`; the app turns it
+into each destination's `DestinationSheet`.
+
+```ts
+interface SheetToSend {
+  week: string
+  status: 'draft' | 'final'
+  entries: Array<{
+    id: string; date: string; start: string; minutes: number; canvasId: string
+    note?: string; worked?: number; source?: string
+  }>
+}
+```
+
+## Files
+
+### `ExtensionFileInfo`
+
+```ts
+interface ExtensionFileInfo { path: string; size: number; mtime: string }
+```
+
+### `ExtensionFiles`
+
+```ts
+interface ExtensionFiles {
+  read(path: string): Promise<Uint8Array | undefined>
+  readText(path: string): Promise<string | undefined>
+  write(path: string, data: string | Uint8Array): Promise<void>
+  append(path: string, text: string): Promise<void>
+  list(dir?: string): Promise<ExtensionFileInfo[]>
+  stat(path: string): Promise<ExtensionFileInfo | undefined>
+  remove(path: string): Promise<void>
+}
+```
+
+## Views (`@devlog/extension-api/view`)
+
+### `ViewContext` (1.6)
+
+```ts
+interface ViewContext { canvasId?: string; date?: string; blockId?: string }
+```
+
+### `ViewToApp` and `AppToView`
+
+The `postMessage` messages between a view and the app; every message carries
+`devlog: 1`. Listed in full in
+[Views and UI → Message protocol](Views-and-UI#message-protocol).
+
+## The context
+
+`DevlogContext` is the `ctx` passed to `activate`; see
+[Extension API Reference](Extension-API-Reference). `ExtensionModule` is the
+shape of `main.js`'s exports:
+
+```ts
+interface ExtensionModule {
+  activate(ctx: DevlogContext): void | Promise<void>
+  deactivate?(): void | Promise<void>
+}
+```
diff --git a/wiki/Extensions-Overview.md b/wiki/Extensions-Overview.md
new file mode 100644
index 0000000..cb07898
--- /dev/null
+++ b/wiki/Extensions-Overview.md
@@ -0,0 +1,183 @@
+# Extensions overview
+
+An extension adds something to Devlog without growing the app: time
+tracking, sending time to Jira, fields on canvases, commands, pages of its
+own. This page is the model; [Extension Quickstart](Extension-Quickstart)
+builds one, and [Extension API Reference](Extension-API-Reference) is the
+reference.
+
+## At a glance
+
+```
+my-extension.devlog-ext.zip
+├── devlog-extension.json   the manifest: what it contributes and asks for
+├── main.js                 one bundled CommonJS file exporting activate(ctx)
+└── views/…                 optional HTML pages for its views
+```
+
+- **One bundled file, no dependencies.** `main.js` exports
+  `activate(ctx)` (and optionally `deactivate()`). Use npm and a bundler to
+  *build* it; ship one file.
+- **It runs in its own process**, a Node child of the Devlog binary, with no
+  access to files, other programs or other extensions (unless the user trusts
+  it; see [Sandbox and Permissions](Sandbox-and-Permissions)).
+- **Everything goes through `ctx`**, a `DevlogContext`, filtered by what the
+  user allowed.
+- **Its views are HTML pages** in sandboxed frames that talk to it only
+  through the app ([Views and UI](Views-and-UI)).
+- **The manifest is read without running any code**: fields, settings,
+  commands, views and node types show up in the app even before the user
+  allows it to run.
+
+## Principles
+
+- **The devlog stays Just A Notebook.** A devlog *names* the extensions it
+  wants and holds their non-secret settings. It never contains their code,
+  their secrets or anything else they need at runtime.
+- **Opening or pulling a devlog never runs code that arrived through git.**
+  Every extension build is allowed explicitly, on each machine.
+- **A leaked devlog leaks no credential.** Secrets live in the OS keychain on
+  each machine.
+- **Extensions go through the same data layer as the app** (`@devlog/core`),
+  so they cannot break the file format.
+- **Extensions cannot see each other's data**, and see the devlog only where
+  the user lets them.
+- **Safe without containers.** Safety comes from what the runtime and the API
+  allow, not from Docker or a VM.
+
+Non-goals: two-way sync with trackers, a public marketplace, a package
+manager, network sandboxing (for now).
+
+## Lifecycle
+
+```
+devlog.json names it ─► app resolves & downloads ─► pinned in devlog.lock.json
+        │                                                  │
+        ▼                                                  ▼
+manifest parsed (contributions shown)        user allows it on this machine
+                                               (read/write scope, trust)
+                                                           │
+                                                           ▼
+                                   process started, code sent over IPC,
+                                   activate(ctx) called (30 s to finish)
+                                                           │
+                                   ┌───────────────────────┴───────────┐
+                                   ▼                                   ▼
+                    commands, views, destinations,          grant changed → restart
+                    providers, events served                revoked / removed → stop
+                                   │                                   │
+                                   ▼                                   ▼
+                          app quits → deactivate() ◄──────────────────┘
+```
+
+1. **Named.** An entry in `devlog.json` under `extensions`.
+2. **Resolved and pinned.** The app downloads the build and records its exact
+   version, URL and SHA-256 in `devlog.lock.json`, so every machine runs
+   byte-identical code.
+3. **Allowed.** The consent dialog shows its name, version, source and
+   permissions and lets the user set the read and write scopes. Consent is
+   per machine, per devlog and per build.
+4. **Activated.** The app starts the process, sends the code and calls
+   `activate(ctx)`. Registration calls (`commands.register`,
+   `views.handle`, `destinations.register`, `provide.*`) belong here.
+5. **Running.** The app calls into it when a command runs, a view calls, a
+   block is posted, the machine pauses, a timesheet is sent, or a view needs
+   data.
+6. **Stopped.** On quit, revoke, removal, or before a restart with a new
+   grant, the app sends `stop`; `deactivate()` runs if exported, then the
+   process exits.
+
+## Sources
+
+Extensions are named in `devlog.json`:
+
+```json
+{
+  "format": 4,
+  "extensions": {
+    "sdeken/devlog-jira": "^1.2.0",
+    "my-ext": "https://example.com/my-ext.devlog-ext.zip",
+    "devlog-time": "builtin"
+  },
+  "settings": {
+    "sdeken.devlog-jira": { "baseurl": "https://acme.atlassian.net" }
+  }
+}
+```
+
+| Entry | Source | Id |
+|---|---|---|
+| `"owner/repo": "<range>"` | GitHub releases: the newest tag matching the range; its `*.devlog-ext.zip` asset | `owner.repo` (lower-cased) |
+| `"name": "https://…/x.zip"` | One exact file | `url.name` |
+| `"name": "builtin"` | Ships inside the app | `builtin.name` |
+
+**The id comes from where an extension was fetched, never from its
+manifest**, so one extension cannot claim another's name to read its data.
+The id names its folders, settings, secrets and grants.
+
+Version ranges are a small subset of semver: `1.2.3` (exact), `^1.2.3`,
+`~1.2.3`, `1.2.x`, `1.x`, `*`, `latest`. Pre-releases match only an exact
+range. Private GitHub repositories work with a GitHub token kept on the
+machine (Extensions page).
+
+### The lockfile
+
+`devlog.lock.json` records, for each GitHub or URL entry, the exact version,
+URL and SHA-256 (built-ins and development folders are not locked). It is
+committed with the next sync. **Check for updates** re-resolves the ranges,
+downloads what changed and rewrites the lockfile; changed code must be
+allowed again. A lockfile updated on another machine is used, and asks for
+consent, the next time the devlog opens here.
+
+Downloads are unpacked into `userData/extensions/<sha256>/`, shared by every
+devlog that pins the same bytes. Nothing is written into the devlog.
+Downloads are capped at 20 MB zipped and 100 MB unpacked.
+
+## Consent and trust
+
+- An extension runs only once allowed, **per machine and per devlog**.
+- The user picks a **read** scope and a **write** scope: nothing, the whole
+  devlog, or chosen canvases (each with everything inside it).
+- **Consent is per build.** A new build of a downloaded extension asks
+  again. A built-in keeps its grant when the app updates it.
+- Changing a grant restarts the extension; revoking stops it; **Remove** takes
+  it out of `devlog.json` and forgets consent on this machine (its data
+  stays).
+- Grants live on the machine, never in the repository, so nothing arriving
+  through git can widen them.
+- An extension that declares `"unrestricted": true` runs only if the user
+  ticks **I trust it**, and then runs outside the sandbox.
+
+## Where an extension's data goes
+
+| Data | Where | Synced | API |
+|---|---|---|---|
+| Devlog-wide settings | `devlog.json` → `settings.<id>` | yes | `ctx.settings` |
+| Per-canvas values | `canvas.md` → `ext.<id>.<key>: value` | yes | `ctx.devlog.field`, `ExtensionCanvas.fields` |
+| Secrets | user data, encrypted with the OS keychain | no | `ctx.secrets` |
+| Its own synced files | `extensions/<id>/` in the devlog | yes | `ctx.files.repo` |
+| Its own machine-only files | `userData/extension-data/<id>/<devlog>/` | no | `ctx.files.local` |
+| Blocks it writes | ordinary day files, marked `ext=<id>` | yes | `ctx.devlog.addBlock` |
+
+Blocks an extension writes are ordinary Markdown in the day files, so they
+survive the extension going away. Uninstalling leaves its folders alone.
+
+## What an extension can contribute
+
+| Contribution | Manifest | Code | Since |
+|---|---|---|---|
+| Canvas fields | `contributes.canvasFields` | `ctx.devlog.field` | 1.0 |
+| Settings and secrets | `contributes.settings`, `secrets`, `check` | `ctx.settings`, `ctx.secrets` | 1.0 |
+| Commands (switcher, keys, menus, note box) | `contributes.commands` | `ctx.commands.register` | 1.0 / 1.6 |
+| Timesheet destinations | `contributes.destinations` | `ctx.destinations.register` | 1.3 |
+| Views (page, status bar, popover, canvas header) | `contributes.views` | `ctx.views.handle` / `post` | 1.5 / 1.6 |
+| Node types | `contributes.nodeTypes` | `ctx.devlog.createCanvas`, `promote` | 1.6 |
+| Focus and time data | — | `ctx.provide.focus` / `activity` | 1.1 / 1.6 |
+| Blocks, canvases, todos | `permissions.read` / `write` | `ctx.devlog.*` | 1.0 – 1.7 |
+
+## Where to go next
+
+- [Extension Quickstart](Extension-Quickstart): build and run one.
+- [Extension Manifest](Extension-Manifest): every manifest field.
+- [Extension API Reference](Extension-API-Reference): every `ctx` member.
+- [Built-in Extensions](Built-in-Extensions): four real extensions to read.
diff --git a/wiki/Getting-Started.md b/wiki/Getting-Started.md
new file mode 100644
index 0000000..fe6cb09
--- /dev/null
+++ b/wiki/Getting-Started.md
@@ -0,0 +1,68 @@
+# Getting started
+
+## Install
+
+Installed builds for Windows and macOS are attached to each
+[GitHub release](https://github.com/sdeken/devlog/releases). They update
+themselves in the background and restart into a new version when you are not
+using the app (macOS builds from CI are not code-signed, so they run but do
+not update themselves).
+
+To run from source you need Node 20+ and `git` on your `PATH`:
+
+```sh
+npm install
+npm run dev        # run with hot reload
+npm run build      # production build into out/
+npm run package    # installers into release/ (package:mac, package:win, package:linux)
+```
+
+Pushing uses whatever credentials git already has (SSH agent, credential
+helper). Devlog never prompts for git credentials.
+
+## Create or open a devlog
+
+A **devlog** is a git repository Devlog writes into. On first launch choose:
+
+- **Create a new devlog**: pick a folder; Devlog runs `git init`, writes
+  `devlog.json` and makes the first commit. You can set a remote now or later
+  (Settings → Repository).
+- **Open an existing devlog**: a clone of one you made on another machine.
+
+Devlog opens on the canvas you last had open.
+
+## Write
+
+1. Make a canvas (a client, a project, a topic) from the sidebar.
+2. Type in the note box at the bottom and press **Enter** to post.
+   **Shift+Enter** starts a new line. Markdown shortcuts work as you type
+   (`**bold**`, `- ` for a list, ```` ```ts ```` for a code block, ⌘B, ⌘I, ⌘K).
+3. Paste or drop an image: it is saved next to the day's file and linked
+   relatively, so the log renders on GitHub too.
+4. Double-click a block (or **Alt+Enter** when posting) to open it as a page
+   and write inside it.
+
+Everything is written to disk immediately and committed shortly after (30
+seconds by default); with a remote, Devlog pulls and pushes every five
+minutes, on **Sync now** (⌘⇧S), on start and on quit.
+
+## Turn on extensions
+
+Open **Extensions** from the quick switcher (⌘P) or Settings. The built-ins
+are added with version `builtin`:
+
+| Extension | What it adds |
+|---|---|
+| `devlog-time` (Time tracking) | Task canvases, the clock, Timesheet and Summary pages, hour targets |
+| `devlog-focus` (Window tracking) | Which window was in front, for the timeline and review (asks to be trusted) |
+| `devlog-jira` (Jira worklogs) | A timesheet destination that writes Jira worklogs |
+| `devlog-cms` (CMS timesheets) | A timesheet destination for the CMS web timesheet |
+
+Each extension asks before it runs, on each machine, and you choose what it
+may read and write. See [Extensions Overview](Extensions-Overview).
+
+## Next
+
+- [Concepts](Concepts): canvases, blocks, tasks and todos.
+- The repository's [README](https://github.com/sdeken/devlog#readme) walks
+  through every feature in detail.
diff --git a/wiki/Home.md b/wiki/Home.md
new file mode 100644
index 0000000..d0e8a9c
--- /dev/null
+++ b/wiki/Home.md
@@ -0,0 +1,55 @@
+# Devlog wiki
+
+Devlog is a desktop app for keeping a running developer log. You write
+posts in a Slack-style WYSIWYG Markdown composer; Devlog stores them as plain
+Markdown files in a git repository and commits and pushes them for you.
+Features beyond notes (time tracking, window tracking, Jira worklogs, CMS
+timesheets) come as **extensions** that each devlog opts into.
+
+This wiki has three audiences. Pick the section that fits.
+
+## Using Devlog
+
+| Page | What it covers |
+|---|---|
+| [Getting Started](Getting-Started) | Install, create or open a devlog, first posts |
+| [Concepts](Concepts) | Canvases, surfaces, blocks, pages, tasks, todos |
+
+## Writing extensions
+
+Start with the overview, build the quickstart, then keep the reference pages
+open while you work.
+
+| Page | What it covers |
+|---|---|
+| [Extensions Overview](Extensions-Overview) | The model: what an extension is, where it comes from, how it is trusted |
+| [Extension Quickstart](Extension-Quickstart) | A working extension, step by step: manifest, code, test, run, release |
+| [Extension Manifest](Extension-Manifest) | Every field of `devlog-extension.json` |
+| [Extension API Reference](Extension-API-Reference) | `DevlogContext` (`ctx`): every namespace, method, permission and error |
+| [Extension Types](Extension-Types) | Every type an extension sees, field by field |
+| [Views and UI](Views-and-UI) | Pages, status bar items, popovers and canvas-header views; the view message protocol |
+| [UI Kit Reference](UI-Kit-Reference) | `@devlog/ui`: the bridge, hooks, components and CSS classes |
+| [Timesheet Destinations](Timesheet-Destinations) | Sending timesheets to Jira, CMS or your own system |
+| [Activity and Time Data](Activity-and-Time-Data) | Pause/resume notices, idle detection, providing time and focus events |
+| [Sandbox and Permissions](Sandbox-and-Permissions) | What the runtime allows, grants, limits, unrestricted extensions |
+| [Testing Extensions](Testing-Extensions) | `@devlog/extension-api/testing`: the in-memory `ctx` |
+| [Built-in Extensions](Built-in-Extensions) | devlog-time, devlog-focus, devlog-jira, devlog-cms as worked examples |
+| [API Versions](API-Versions) | What arrived in each API version, 1.0 to 1.7 |
+| [Troubleshooting Extensions](Troubleshooting-Extensions) | Common errors and what they mean |
+
+## Working on Devlog itself
+
+| Page | What it covers |
+|---|---|
+| [Architecture](Architecture) | Processes, packages, where code lives |
+| [Storage Format](Storage-Format) | The repository layout and every file format |
+| [Core Library](Core-Library) | `@devlog/core`: `DevlogStore`, `RepoIndex`, `SyncManager` and friends |
+| [Extension Host Protocol](Extension-Host-Protocol) | How the app runs an extension process and talks to it |
+| [Development](Development) | Building, testing, the smoke test, cutting a release |
+
+## Versions
+
+This wiki describes Devlog **0.18.0**, extension API **1.7.0**, storage
+format **4**. The longer design notes live in the repository under
+[`docs/`](https://github.com/sdeken/devlog/tree/main/docs); the wiki links to
+them where they go deeper.
diff --git a/wiki/Sandbox-and-Permissions.md b/wiki/Sandbox-and-Permissions.md
new file mode 100644
index 0000000..75303ca
--- /dev/null
+++ b/wiki/Sandbox-and-Permissions.md
@@ -0,0 +1,132 @@
+# Sandbox and permissions
+
+The model: **you trust what you install**, like a VS Code extension, but
+with limits enforced by the runtime, and trust is explicit. No Docker, no
+VM: safety comes from what the runtime and the API allow.
+
+## The sandbox
+
+An extension runs in **its own process**: a Node child of the Devlog binary
+(`ELECTRON_RUN_AS_NODE`) started with Node's permission model
+(`--permission`), allowed to read exactly one file, the host script. Its
+code is sent over the message channel and evaluated, so it needs no file
+access to load.
+
+| An extension… | Because |
+|---|---|
+| **cannot touch files** | The permission model allows reading only the host script. Its own folders are reached through `ctx.files`, a broker in the app. |
+| **cannot start programs, load native code or spawn workers** | The permission model denies them. Node built-ins can be required, but the calls fail with `ERR_ACCESS_DENIED`. |
+| **cannot `require` packages** | Only Node built-ins resolve; anything else throws `Extensions are bundled: cannot load "…"`. |
+| **sees the devlog only through its grant** | Every `ctx.devlog` call is filtered by the app. |
+| **cannot reach other extensions, the app's windows or Electron** | Each has its own message channel to the app and nothing else. (The exception: sending a timesheet through another extension's destination, with `permissions.send`, through the app.) |
+| **cannot take the app down** | A crash kills only its process. The heap is capped at 256 MB; the environment is stripped to a few locale variables (`TZ`, `LANG`, `LC_ALL`, and `SystemRoot`/`windir` on Windows); one that does not start within 30 seconds is stopped; calls that take too long fail. |
+| **shows UI only in sandboxed frames** | Views run in `sandbox="allow-scripts"` frames with a CSP that forbids network, frames and forms ([Views and UI](Views-and-UI#how-a-view-is-served)). |
+
+**The network is not restricted.** An extension can make any request with
+`fetch`; the domains it declares in `permissions.network` are shown at
+consent but not enforced. So an extension can send out whatever it can read,
+which is one reason read access is scoped.
+
+Electron's `utilityProcess` silently ignores `--permission`, hence the Node
+child; the builds must keep Electron's `RunAsNode` fuse on. The test suite
+runs a probe extension (`tests/fixtures/extensions/probe`) in that process
+and checks that file access, child processes and workers are refused.
+
+## Permissions
+
+Declared in the manifest, shown before the extension first runs:
+
+| Permission | The user chooses | Effect |
+|---|---|---|
+| `read: true` | A read scope: the whole devlog, or chosen canvases (each with everything inside) | `days`, `blocks`, `search`, `todos`, `range`, `activity`, `onBlockAdded` and command block context work within the scope. |
+| `write: true` | A write scope, the same way | `addBlock`, `editBlock`, `promote`, `createCanvas`, `updateCanvas` work within the scope. Top-level canvases need write access to the whole devlog. |
+| `network: [...]` | — | Shown only. |
+| `send: true` | — | May send timesheets through other extensions' destinations (1.7). |
+| `unrestricted: true` | Whether to tick **I trust it** | Runs outside the sandbox (below). |
+
+What an extension gets **with no grant at all**: its own settings, secrets
+and files; the canvas fields it declared (for canvases it can list); its
+destinations receiving sheets the user sends; its views, commands and
+providers.
+
+### What the grant hides
+
+- `canvases()` lists canvases in the read or write scope plus their
+  ancestors (so they can be named), plus canvases it keeps; nothing else.
+- `search`, `todos` and `range` return nothing outside the read scope (and
+  empty results with no read grant).
+- `days`, `blocks` and `activity` throw outside it.
+- Writes outside the write scope fail.
+- Command contexts leave out canvases it cannot see, and blocks on canvases
+  it cannot read.
+- `activity` shows task time on unreadable canvases as `canvasId: null`, and
+  window titles only with read access to the whole devlog.
+- Canvases it keeps (`managedCanvas`) are its own whatever the grant.
+
+### Consent is per machine, per devlog, per build
+
+- Consent is keyed by the devlog folder and stored on the machine, **never
+  in the repository**, so nothing arriving through git can widen it.
+- A new build of a downloaded extension (or any change to a development
+  folder) asks again. A **built-in** keeps its grant and trust when the app
+  brings a new build.
+- Changing a grant restarts the extension; revoking stops it until allowed
+  again; **Remove** takes it out of `devlog.json` and forgets consent here.
+
+## Unrestricted extensions
+
+An extension that needs what the sandbox forbids (start a platform helper,
+read files) declares:
+
+```json
+"permissions": { "unrestricted": true }
+```
+
+It runs only if the user ticks **I trust it** when allowing it (otherwise:
+`… runs unrestricted; it can only run if you say you trust it`), and then runs
+**without the permission model**: full file-system and process access, the
+app's environment, and `ctx.packageDir` (its own unpacked folder, for scripts
+it ships). The API calls are still filtered by its grant, but nothing stops
+it reading the repository directly, so ask for it only when you must.
+devlog-focus (window tracking) is one.
+
+## The file broker
+
+`ctx.files.repo` and `ctx.files.local` go through `ExtensionFileStore`
+(`packages/core/src/node/extensionFiles.ts`), which:
+
+- takes relative, `/`-separated paths only and refuses absolute paths,
+  drive letters, `.`/`..`, backslashes, reserved characters, Windows device
+  names and alternate data streams;
+- refuses to go through a symlink anywhere between the devlog root and the
+  target (git can commit links);
+- writes atomically (temp file, then rename) and serialises writes;
+- caps sizes: 16 MB per file, 256 MB per folder, 20 000 files.
+
+## Secrets
+
+`ctx.secrets` values are stored per extension in user data, encrypted with
+the OS keychain (Electron `safeStorage`). They are never written to the
+devlog, so a leaked or public devlog repository leaks no credential. Each
+machine has its own copy; the user enters them on each machine.
+
+## Blocks written by extensions
+
+Blocks an extension adds carry `ext=<id>` in their marker and are automatic
+blocks: read-only in the app (a todo can still be ticked), shown with a
+muted brace. They go through the same data layer as the app
+(`@devlog/core`), so an extension cannot break the file format (marker
+escaping, append-only files, image paths). They are ordinary Markdown in the
+day files and survive the extension going away.
+
+## Downloads
+
+- GitHub and URL extensions are pinned by SHA-256 in `devlog.lock.json`, so
+  every machine runs byte-identical code.
+- Zips are capped at 20 MB, unpacked contents at 100 MB.
+- Unpacked into `userData/extensions/<sha256>/`, never into the devlog.
+
+## Not built yet
+
+- Enforcing the declared network domains.
+- A command to delete an extension's data.
diff --git a/wiki/Storage-Format.md b/wiki/Storage-Format.md
new file mode 100644
index 0000000..af8fcbd
--- /dev/null
+++ b/wiki/Storage-Format.md
@@ -0,0 +1,242 @@
+# Storage format
+
+A devlog is a git repository of plain Markdown with a little front matter
+and HTML-comment markers. **The files are the source of truth**: every cache
+can be deleted and rebuilt from them, and they render on GitHub and open in
+any editor. This page describes **storage format 4** (block file format 3).
+Only `@devlog/core` writes these files; see [Core Library](Core-Library).
+
+## Repository layout
+
+```
+devlog.json                       { "format": 4, … }: storage format, extensions, their settings
+devlog.lock.json                  exact extension builds, pinned by SHA-256
+.gitattributes                    union merge for block files and activity logs
+.gitignore
+entries/…                         the old journal (retired; only in devlogs that used it)
+canvases/
+  k3/                             shard: the first two characters of the id
+    k3m9x2q7vd/                   a canvas ("Acme Corp")
+      canvas.md                   its properties + its surface
+      assets/                     images pasted into the surface
+      entries/2026/09/
+        2026-09-19.md             its stream: one file per local day
+        assets/2026-09-19-143201-a1b2.png   images pasted into blocks
+  7w/
+    7wq0dz4hbe/                   "Website", parent: k3m9x2q7vd
+activity/
+  desktop-4f1a/2026/09/2026-09-19.jsonl   the app's activity log, one folder per machine
+extensions/
+  builtin.devlog-time/…           each extension's own synced files
+```
+
+## `devlog.json`
+
+```json
+{
+  "format": 4,
+  "extensions": {
+    "devlog-time": "builtin",
+    "sdeken/devlog-jira": "^1.2.0",
+    "my-ext": "https://example.com/my-ext.devlog-ext.zip"
+  },
+  "settings": {
+    "builtin.devlog-time": { "idle_minutes": "10", "in_repo": "true" },
+    "sdeken.devlog-jira": { "baseurl": "https://acme.atlassian.net" }
+  }
+}
+```
+
+- `format`: the storage format. The app upgrades format 3 to 4 when it opens
+  a devlog, and refuses anything else (older or newer) with a message
+  (`assertSupportedFormat`).
+- `extensions`: see [Extensions Overview → Sources](Extensions-Overview#sources).
+- `settings`: per extension **id**, string values only. Never secrets.
+
+## `devlog.lock.json`
+
+```json
+{
+  "lockfileVersion": 1,
+  "extensions": {
+    "sdeken/devlog-jira": {
+      "id": "sdeken.devlog-jira",
+      "spec": "^1.2.0",
+      "version": "1.2.3",
+      "url": "https://github.com/sdeken/devlog-jira/releases/download/v1.2.3/devlog-jira.devlog-ext.zip",
+      "sha256": "…"
+    }
+  }
+}
+```
+
+Keyed by the `devlog.json` key; written sorted. Built-ins and development
+folders are not locked.
+
+## `.gitattributes`
+
+```
+# Devlog: append-only files merge by keeping both sides
+**/entries/**/*.md merge=union
+**/todos.md merge=union
+activity/**/*.jsonl merge=union
+extensions/<id>/<glob> merge=union      one line per appendOnly glob of each extension
+```
+
+Git's union driver keeps both sides of a conflicting hunk. That is safe
+because these files are append-only logs whose readers tolerate records in
+any order.
+
+## Canvases: `canvas.md`
+
+```markdown
+---
+title: Website
+parent: k3m9x2q7vd
+created: 2026-09-19T10:00:00.000Z
+type: sdeken.devlog-kanban/board
+repo: "C:\\src\\acme-site"
+alias: website
+ext.builtin.devlog-jira.issue: ACME-123
+---
+
+Marketing site rebuild. Weekly sync on Tuesdays.
+
+- Tracker: https://issues.example.com/acme
+```
+
+- **Ids** are 10 random characters from `0123456789abcdefghjkmnpqrstvwxyz`
+  (no `i l o u`), about 50 bits, so machines creating canvases offline never
+  collide. The folder is `canvases/<first two characters>/<id>/`.
+- **The hierarchy is `parent: <id>`**, not the folder path: renaming or
+  moving a canvas edits one line and never moves files.
+- Front matter is `key: value` lines (values optionally quoted); no YAML
+  library.
+
+| Key | Meaning |
+|---|---|
+| `title` | The canvas's name |
+| `parent` | The enclosing canvas's id (absent at the top level) |
+| `created`, `updated` | Creation time; last surface edit |
+| `task: true` | devlog-time's task type (written this way for compatibility) |
+| `type: <ext id>/<type id>` | Any other node type |
+| `repo` | A linked git working copy (repeatable) |
+| `archived: true` | Archived, with everything beneath it |
+| `alias` | A former id that still resolves here (repeatable) |
+| `ext.<extension id>.<key>` | An extension's canvas field |
+| `devlog.managed` | The owner of a canvas an extension keeps (`<ext id>/<key>`) |
+
+The **surface** is the Markdown after the front matter. Its images live in
+`assets/` beside `canvas.md` and are linked relatively.
+
+## Blocks: day files
+
+Each canvas's stream is one file per **local** day:
+`…/entries/YYYY/MM/YYYY-MM-DD.md`. A day file is an **append-only log of
+records** (`packages/core/src/format/oplog.ts`):
+
+```markdown
+<!-- devlog:format 3 -->
+<!-- devlog:add id=k2m4x9qa pos=a0 at=2026-09-19T14:32:01.000Z -->
+Kickoff with **Dana**. Scope agreed.
+<!-- devlog:add id=p7w2c0dd parent=k2m4x9qa pos=a0 at=2026-09-19T14:40:12.000Z kind=todo -->
+Send the estimate
+<!-- devlog:edit id=k2m4x9qa at=2026-09-19T15:02:44.000Z -->
+Kickoff with **Dana**. Scope agreed; estimate by Friday.
+<!-- devlog:set id=p7w2c0dd at=2026-09-20T09:00:00.000Z done=2026-09-20T09:00:00.000Z -->
+<!-- devlog:add id=q1r8s2t0 pos=a1 at=2026-09-19T16:10:00.000Z ext=sdeken.devlog-deploys env=staging -->
+Deployed **v2.3** to staging
+```
+
+| Record | Form | Meaning |
+|---|---|---|
+| `add` | `id= [parent=] pos= at= [updated=] [kind=] [hidden=1] [key=value…]` + body | A new block |
+| `edit` | `id= at=` + body | New text |
+| `set` | `id= [pos= [parent=]] at= [hidden=0\|1] [kind=] [key=value \| key=""]` | Move, hide, change kind or metadata (`key=""` removes one) |
+| `delete` | `id= at=` | Delete (final) |
+
+Block ids are 8 characters of `0-9a-z`, unique within the file.
+
+### Replay rules
+
+The current blocks are a replay of the records, designed so the result does
+not depend on the order two machines' records were merged in:
+
+- Each field (body, placement, hidden, kind, each metadata key) is a
+  **last-writer-wins register on `at`**; equal timestamps go to the later
+  record. New records are stamped no earlier than the newest in the file, so
+  a slow clock cannot make a fresh edit lose.
+- `delete` is final; records for unknown ids are ignored; `add` records apply
+  first, so a record merged in above its block still applies.
+- A block whose parent is missing or deleted shows at the top level; a
+  parent cycle (two concurrent moves) is cut at its smallest id.
+- A line that starts like a marker but is not a complete record (a torn
+  write, a record type from a newer version) ends the previous body and is
+  otherwise skipped.
+- Anything before the first record is ignored, not destroyed; CRLF is fine.
+
+### Order keys
+
+Siblings sort by `pos`, a fractional index (`a0`, `a1`, `a0V`, …;
+`format/order.ts`): there is always a key between two keys, and appends only
+grow the integer part. Ties (two machines appending at once) sort by
+creation time, then id.
+
+### Marker escaping
+
+Any body line that looks like a marker (`<!-- devlog:…`, possibly after
+backslashes) gets one more leading backslash on disk and loses it on
+reading, so no text can split or merge blocks. A seeded fuzz test round-trips
+hostile bodies.
+
+### Image paths
+
+On disk, images are relative to the day file (`![shot](assets/x.png)`), so
+the log renders on GitHub. In memory (and in the API) they are
+repo-root-relative (`canvases/k3/k3m9x2q7vd/entries/2026/09/assets/x.png`).
+
+### Trees across days
+
+A block written inside another on a later day is stored in its **root
+block's day file**, so a subtree never splits across files. Moving a block
+to another canvas appends `add` records to the target and `delete` records
+to the source.
+
+### Compaction
+
+`DevlogStore.compact({ quietSince, dryRun })` rewrites a quiet file as one
+`add` per live block, after checking that the result replays to the same
+blocks. It exists and is tested but the app does not call it yet.
+
+## Activity log
+
+`activity/<machine>/YYYY/MM/YYYY-MM-DD.jsonl`: one JSON object per line,
+one file per local day, one folder per machine (`<host>-<short id>`, kept in
+`userData/machine.json`). Written only while an extension provides time.
+
+```json
+{"t":"2026-09-19T09:02:11.000Z","type":"unlock"}
+{"t":"2026-09-19T09:40:00.000Z","type":"git","canvasId":"k3m9x2q7vd","repo":"C:\\src\\acme-site","action":"checkout","branch":"feature/login","from":"main"}
+{"t":"2026-09-19T12:00:00.000Z","type":"idle"}
+{"t":"2026-09-19T13:00:00.000Z","type":"exclude","id":"x1","start":"2026-09-19T12:00:00.000Z","end":"2026-09-19T12:45:00.000Z"}
+```
+
+Types are those of [`ActivityRecord`](Extension-Types#activityrecord-17). A
+machine only appends to its own files, so logs never conflict; readers merge
+every machine and tag each event with it. Corrections are `exclude` events,
+undone by a later event with `cancels: <id>`; raw events are never edited.
+
+## Extension folders
+
+`extensions/<id>/…` holds each extension's synced files (`ctx.files.repo`).
+The core ignores this folder when listing, indexing and searching. Writes
+there do not count as unsaved work; they are committed with the next interval
+sync.
+
+## Older devlogs
+
+- Format 3 is upgraded on open (`upgradeStorage`: per-canvas `todos.md` lists
+  move into the streams as `todo` blocks).
+- Formats 1 and 2 (before Devlog 0.5) are refused: open the devlog once with
+  Devlog 0.5, which upgrades it, then with this version.
+- A newer format is refused rather than misread.
diff --git a/wiki/Testing-Extensions.md b/wiki/Testing-Extensions.md
new file mode 100644
index 0000000..bc3495d
--- /dev/null
+++ b/wiki/Testing-Extensions.md
@@ -0,0 +1,136 @@
+# Testing extensions
+
+`@devlog/extension-api/testing` gives you an in-memory `ctx`, so an
+extension's logic can be unit-tested without Devlog, Electron or a git
+repository. Source:
+[`packages/extension-api/src/testing.ts`](https://github.com/sdeken/devlog/blob/main/packages/extension-api/src/testing.ts).
+
+```ts
+import { expect, test } from 'vitest'
+import { createTestContext } from '@devlog/extension-api/testing'
+import * as ext from '../src/main'
+
+test('hello counts', async () => {
+  const t = createTestContext({ settings: { greeting: 'Hi' } })
+  await ext.activate(t.ctx)
+  await t.run('hello')
+  await t.run('hello')
+  expect(t.notifications).toEqual(['Hi #1', 'Hi #2'])
+  expect(new TextDecoder().decode(t.files.local.get('count'))).toBe('2')
+})
+```
+
+It follows the real rules where they matter to an extension: files are
+reached by relative paths only, reads and writes respect the grant you give
+it, blocks it adds are marked `meta.ext = <id>`, a kind is only allowed on a
+kept canvas, and sending needs a final sheet.
+
+## `createTestContext(options)`
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `id` | `string` | `test.extension` | `ctx.id` |
+| `machine` | `string` | `test-machine-0000` | `ctx.machine` |
+| `packageDir` | `string \| null` | `null` | `ctx.packageDir` (non-null: as if unrestricted) |
+| `canvases` | `TestCanvas[]` | `[]` | Canvases, each with `days: { [date]: ExtensionBlock[] }`. Mutated as the extension adds blocks. |
+| `settings` | `Record<string, string>` | `{}` | `ctx.settings` |
+| `secrets` | `Record<string, string>` | `{}` | Initial secrets |
+| `read` | `string[] \| 'all' \| null` | all | Canvas ids it may read (with what is beneath them) |
+| `write` | `string[] \| 'all' \| null` | all | Canvas ids it may write to |
+| `activity` | `ActivityRecord[]` | `[]` | What `devlog.activity` answers, filtered to the dates asked for (1.7) |
+| `destinations` | `Array<DestinationInfo & { destination }>` | `[]` | Other extensions' destinations it can send through (1.7) |
+| `confirm` | `boolean` | `true` | The answer to every `ui.confirm` |
+| `now` | `() => Date` | `() => new Date()` | The clock used for block times, dates and file mtimes |
+
+`TestCanvas` is an `ExtensionCanvas` plus optional `days`. Give each test its
+own copies (for example with `structuredClone`), since the harness adds
+blocks to them.
+
+## What it records
+
+| Property | Contents |
+|---|---|
+| `ctx` | The `DevlogContext` to pass to `activate` |
+| `notifications` | Messages passed to `ui.notify`, in order |
+| `confirmations` | Questions passed to `ui.confirm` |
+| `added` | `{ canvasId, date, block }` for every `devlog.addBlock` |
+| `created` | Ids of canvases made with `devlog.createCanvas` (1.6) |
+| `files` | `{ repo, local }`: `Map<path, Uint8Array>` for the two folders |
+| `secrets` | `Map<key, value>` |
+| `picks` | `{ items, placeholder }` for every `ui.pick` (1.6) |
+| `opened` | `ui.open` targets (1.6) |
+| `openedPages` | `ui.openPage` view ids (1.7) |
+| `app` | `{ trayLabel, keepRunning, idleMinutes, highlight }`: what it asked of the app (1.6) |
+| `viewMessages` | `Map<viewId, unknown[]>`: messages sent with `views.post` |
+
+## What it drives
+
+| Method | Does what the app would |
+|---|---|
+| `run(commandId, context?)` | Runs a registered command with a `CommandContext` (default `source: 'switcher'`); resolves with its return value. |
+| `post(canvasId, date, block)` | Someone posted a block in the app: it is added to that day and `onBlockAdded` listeners hear it (1.6). |
+| `notice(n)` | Delivers an `ActivityNotice` (pause/resume) to `activity.on` listeners. |
+| `setSettings(s)` | Replaces the settings and calls `settings.onChange` listeners. |
+| `answerPick` | Assignable: `(items) => id \| null` decides what `ui.pick` returns (default: the first item). |
+| `viewCall(viewId, method, ...args)` | Calls a view's handler, as its page would (1.5). |
+| `preview(destinationId, sheet)` / `send(destinationId, sheet)` | Calls a registered destination, as the Send dialog would (1.3). |
+| `focus(from, to)` | Asks the registered focus provider. |
+| `timeEvents(from, to)` | Asks the registered activity provider (1.6). |
+| `commands()` | The ids of registered commands. |
+
+## Recipes
+
+### Grants
+
+```ts
+const t = createTestContext({ canvases, read: ['acme'], write: [] })
+await ext.activate(t.ctx)
+await expect(t.run('post', { canvasId: 'acme' })).rejects.toThrow('No write access')
+```
+
+### A command on a block
+
+```ts
+await t.run('maketask', { source: 'menu', canvasId: 'acme', date: '2026-09-22', blockId: 'b1' })
+expect(t.created).toHaveLength(1)
+```
+
+### Reacting to posts and pauses
+
+```ts
+t.post('task1', '2026-09-22', { id: 'n1', createdAt: '2026-09-22T09:00:00Z', markdown: 'Started on it' })
+t.notice({ t: '2026-09-22T09:30:00Z', type: 'pause', reason: 'locked' })
+expect(await t.timeEvents('2026-09-22', '2026-09-22')).toMatchObject([{ type: 'task', canvasId: 'task1' }])
+```
+
+### Views
+
+```ts
+expect(await t.viewCall('status', 'status')).toEqual({ active: null })
+await t.run('start', { canvasId: 'task1' })
+expect(t.viewMessages.get('status')?.at(-1)).toMatchObject({ active: 'task1' })
+```
+
+### A fixed clock
+
+```ts
+let clock = new Date('2026-09-22T09:00:00Z')
+const t = createTestContext({ now: () => clock })
+// …
+clock = new Date('2026-09-22T10:00:00Z')
+```
+
+### Network calls
+
+Stub `fetch` with your test runner (`vi.stubGlobal('fetch', vi.fn(async () => new Response('{}')))`
+in Vitest) and assert on the requests.
+
+## Testing in the real host
+
+The harness does not run the sandbox. Devlog's own tests start real
+extensions in the real host process: `tests/extensions.test.ts` with the
+fixtures in `tests/fixtures/extensions/` (`probe` exercises the API and
+checks that the sandbox refuses files, child processes and workers; `shaper`
+covers node types and commands; `trusted` runs unrestricted). To try yours in
+the app, use the development override described in
+[Extension Quickstart → Run it in Devlog](Extension-Quickstart#6-run-it-in-devlog).
diff --git a/wiki/Timesheet-Destinations.md b/wiki/Timesheet-Destinations.md
new file mode 100644
index 0000000..27921ba
--- /dev/null
+++ b/wiki/Timesheet-Destinations.md
@@ -0,0 +1,203 @@
+# Timesheet destinations
+
+A **destination** (API 1.3) is somewhere a finished weekly timesheet can be
+sent: Jira worklogs, a CMS timesheet, an invoicing system, a CSV file. The
+time extension (devlog-time) builds the timesheet; a destination extension
+turns its entries into lines in the external system.
+
+Two roles:
+
+| Role | Needs | API |
+|---|---|---|
+| **Destination**: receives a week and sends it on | `contributes.destinations` | `ctx.destinations.register(id, { preview, send })` (1.3) |
+| **Sender**: hands a week to destinations | `permissions.send` | `ctx.destinations.list()`, `preview(to, sheet)`, `send(to, sheet)` (1.7) |
+
+devlog-jira and devlog-cms are destinations; devlog-time is the sender.
+The full timesheet design (rounding, trims, storage) is in
+[`docs/TIMESHEETS.md`](https://github.com/sdeken/devlog/blob/main/docs/TIMESHEETS.md).
+
+## The flow
+
+```
+devlog-time Timesheet page
+   │  user presses Send → picks a destination
+   ▼
+ctx.destinations.preview(to, sheet)  ──► app builds a DestinationSheet for that
+                                          extension (labels + its canvas fields)
+                                     ──► destination.preview(sheet) → DestinationLine[]
+   │  user reviews the preview, confirms
+   ▼
+ctx.destinations.send(to, sheet)     ──► app refuses unless status === 'final'
+                                     ──► destination.send(sheet) → SendResult
+   │
+   ▼
+devlog-time writes "Sent to Jira: …" under the week's timesheet block
+```
+
+**Pressing Send is the user's consent for that week's entries**, so a
+destination needs **no read grant**: everything it needs is in the sheet.
+
+## Writing a destination
+
+### 1. Declare it, and the fields it maps by
+
+```json
+{
+  "name": "devlog-invoicer",
+  "displayName": "Invoicer",
+  "version": "1.0.0",
+  "api": "^1.3.0",
+  "main": "main.js",
+  "contributes": {
+    "destinations": [{ "id": "hours", "label": "Invoicer" }],
+    "canvasFields": [{ "key": "project", "label": "Invoicer project id", "placeholder": "P-1042" }],
+    "settings": [{ "key": "baseurl", "label": "Invoicer address", "type": "url", "required": true }],
+    "secrets": [{ "key": "token", "label": "API token", "required": true }],
+    "commands": [{ "id": "check", "label": "Check the Invoicer connection" }],
+    "check": "check"
+  },
+  "permissions": { "network": ["invoicer.example.com"] }
+}
+```
+
+The user sets the canvas field on the canvases that map to something (a
+client, a project, a task); canvases inside inherit it.
+
+### 2. Register it
+
+```js
+exports.activate = async (ctx) => {
+  ctx.destinations.register('hours', {
+    async preview(sheet) {
+      return plan(sheet, await readLedger(ctx, sheet.week))
+    },
+    async send(sheet) {
+      const ledger = await readLedger(ctx, sheet.week)
+      const done = []
+      const failed = []
+      for (const line of plan(sheet, ledger)) {
+        if (line.action === 'skip' || line.action === 'unchanged') continue
+        try {
+          ledger[line.id] = await push(ctx, line)       // your API call
+          done.push(line.id)
+        } catch (err) {
+          failed.push({ lineId: line.id, error: err.message })
+        }
+      }
+      await ctx.files.repo.write(`sent/${sheet.week}.json`, JSON.stringify(ledger, null, 2) + '\n')
+      return { done, failed, summary: `${done.length} lines sent${failed.length ? `, ${failed.length} failed` : ''}` }
+    }
+  })
+}
+
+async function readLedger(ctx, week) {
+  return JSON.parse((await ctx.files.repo.readText(`sent/${week}.json`)) ?? '{}')
+}
+
+function plan(sheet, ledger) {
+  return sheet.entries.map((e) => {
+    const project = e.fields.project // inherited from the nearest canvas that sets it
+    const base = { id: e.id, entryIds: [e.id], date: e.date, start: e.start, minutes: e.minutes, target: project ?? '', description: e.note }
+    if (!project) return { ...base, action: 'skip', reason: `No Invoicer project on ${e.task}` }
+    const prev = ledger[e.id]
+    if (!prev) return { ...base, action: 'create' }
+    return { ...base, action: prev.minutes === e.minutes && prev.project === project ? 'unchanged' : 'update' }
+  })
+}
+```
+
+### What the destination receives: `DestinationSheet`
+
+```ts
+{
+  week: '2026-09-21',            // the Monday
+  status: 'final',               // send() is only ever called with 'final'
+  entries: [{
+    id: 'e3',                    // stable within the week: key your ledger by it
+    date: '2026-09-22',
+    start: '2026-09-22T07:00:00.000Z', // on a local quarter hour
+    minutes: 90,                 // a multiple of 15
+    note: 'Login bug',
+    canvasId: 'k3m9x2q7vd',
+    task: 'Acme / Website / Login bug',
+    client: 'Acme',
+    fields: { project: 'P-1042' } // this extension's canvas fields, inherited
+  }]
+}
+```
+
+### What it returns
+
+- `preview(sheet)` → `DestinationLine[]`: one line per thing it would do
+  (`create`, `update`, `delete`, `unchanged`, or `skip` with a `reason`),
+  each listing the `entryIds` it covers. Lines with other actions or without
+  an `id` are dropped; `description` is cut to 500 characters, `reason` to
+  300. Preview must not change anything.
+- `send(sheet)` → `SendResult`: `done` (line ids that went through),
+  `failed` (`{ lineId, error }`), and a one-sentence `summary` for the record
+  ("3 worklogs created, 1 updated"). Errors and the summary are cut to 500
+  characters.
+
+Throwing from either shows the error in the Send dialog. Preview has 2
+minutes, send 10.
+
+### Keep a ledger
+
+The app does not remember what was sent; **each destination keeps its own
+ledger** in `ctx.files.repo` (synced), keyed by entry id (or by whatever its
+lines are). That makes sending idempotent:
+
+- pressing Send twice, or on a second machine, sends only what changed;
+- a correction after the fact becomes an `update`;
+- an entry that disappeared becomes a `delete` (walk the ledger for ids no
+  longer in the sheet).
+
+devlog-jira's ledger is `sent/<week>.json`: entry id → issue, worklog id and
+what was sent. devlog-cms keys by assignment and day, and compares with what
+CMS shows.
+
+## Sending through destinations (1.7)
+
+An extension with `"permissions": { "send": true }` can drive destinations
+itself, as devlog-time's Timesheet page does:
+
+```js
+const dests = await ctx.destinations.list()
+// [{ extension: 'devlog-jira', from: 'Jira worklogs', id: 'worklogs', label: 'Jira' }, …]
+
+const to = { extension: dests[0].extension, id: dests[0].id }
+const sheet = {
+  week: '2026-09-21',
+  status: 'final',
+  entries: [{ id: 'e1', date: '2026-09-22', start: '2026-09-22T07:00:00.000Z', minutes: 90, canvasId: 'k3m9x2q7vd', note: 'Login bug' }]
+}
+const lines = await ctx.destinations.preview(to, sheet)
+const result = await ctx.destinations.send(to, sheet) // only for status 'final'
+```
+
+- `to.extension` is the destination extension's **devlog.json key** (as
+  `list()` returns it), not its id.
+- The app validates the sheet (the week must be a Monday, every entry's date
+  inside it) and builds each destination's `DestinationSheet` from it, adding
+  labels and that destination's own canvas fields.
+- `send` throws `Mark the timesheet final before sending it` for a draft,
+  and `… is not ready to send` if the destination extension is not running.
+- Without `permissions.send`: `Sending through destinations needs
+  "permissions": { "send": true }`.
+
+## Testing a destination
+
+```ts
+import { createTestContext } from '@devlog/extension-api/testing'
+import * as ext from '../src/main'
+
+const t = createTestContext({ settings: { baseurl: 'https://invoicer.example.com' }, secrets: { token: 'x' } })
+await ext.activate(t.ctx)
+const lines = await t.preview('hours', { week: '2026-09-21', status: 'final', entries: [/* DestinationEntry[] */] })
+expect(lines.map((l) => l.action)).toEqual(['create', 'skip'])
+const res = await t.send('hours', { week: '2026-09-21', status: 'final', entries: [/* … */] })
+expect(t.files.repo.has('sent/2026-09-21.json')).toBe(true)
+```
+
+Mock `fetch` (`vi.stubGlobal('fetch', …)`) for the network calls. See
+[Testing Extensions](Testing-Extensions).
diff --git a/wiki/Troubleshooting-Extensions.md b/wiki/Troubleshooting-Extensions.md
new file mode 100644
index 0000000..83b6f5c
--- /dev/null
+++ b/wiki/Troubleshooting-Extensions.md
@@ -0,0 +1,87 @@
+# Troubleshooting extensions
+
+Error messages come from the app and are meant to be read by people; most
+say what to fix. This page groups the common ones.
+
+## Seeing what happened
+
+- **Console output.** `console.log` / `console.error` in the extension
+  process go to the app's stdout/stderr, each line prefixed `[ext <id>]`.
+  Run the app from a terminal (`npm run dev` in a Devlog checkout, or the
+  installed binary from a shell) to see them.
+- **The Extensions page** shows each extension's state (starting, running,
+  failed, stopped) and the error that stopped it.
+- **Unit tests** with `@devlog/extension-api/testing` reproduce most API
+  errors without the app ([Testing Extensions](Testing-Extensions)).
+
+## It does not load
+
+| Symptom / message | Cause and fix |
+|---|---|
+| `Invalid extension manifest: …` | The manifest is rejected; the message lists every problem. See [Extension Manifest → Common manifest errors](Extension-Manifest#common-manifest-errors). |
+| `The extension does not export activate(ctx)` | `main.js` must be CommonJS setting `exports.activate` (or `module.exports.default.activate`). Bundle with `--format=cjs`. |
+| `Extensions are bundled: cannot load "…"` | `require` of a package. Bundle your dependencies (esbuild `--bundle --platform=node`). |
+| `Did not start within 30 seconds` | `activate` must only register things; move slow work (network, reading big files) into the background: `void warmUp()`. |
+| `… runs unrestricted; it can only run if you say you trust it` | The manifest says `unrestricted: true`; tick **I trust it** when allowing it, or drop the permission. |
+| `ERR_ACCESS_DENIED` | The sandbox refused `fs`, `child_process`, `worker_threads` or a native addon. Use `ctx.files`, or (only if you must) `unrestricted`. |
+| `Not installed` / download errors | Check the `devlog.json` entry: `owner/repo` with a range that matches a release tag, a release asset named `*.devlog-ext.zip`, under 20 MB zipped and 100 MB unpacked. Private repositories need a GitHub token on the Extensions page. |
+| It keeps asking for consent | Consent is per build. Every change to a development folder, and every new downloaded version, asks again. |
+| `… needs extension API ^1.8.0; this Devlog provides 1.7.0` | The app loads an extension only if its version satisfies the manifest's `api` range. Declare the lowest version you need (`^1.6.0`), and feature-detect newer members with `ctx.apiVersion`. |
+
+## Permission errors
+
+| Message | Meaning |
+|---|---|
+| `No access to that canvas` | The canvas is outside both scopes (and not an ancestor of one). `ui.open`, `ui.highlight` and `devlog.field` need a canvas `canvases()` lists. |
+| `No read access to that canvas` | `days` / `blocks` outside the read scope. |
+| `No read access` | `devlog.activity` with no read grant. |
+| `No write access to that canvas` | A write outside the write scope. |
+| `No write access to where it would go` | `updateCanvas` moving a canvas somewhere it may not write. |
+| `Only an extension that may write everywhere can make a top-level canvas` | `createCanvas` without `parentId` needs a whole-devlog write scope. |
+| `That canvas has another extension's type` | `updateCanvas` may only set or clear its own node types. |
+| `Only blocks it added` | `editBlock` on someone else's block (allowed only on a canvas it keeps). |
+| `Sending through destinations needs "permissions": { "send": true }` | Add `send` to the manifest's permissions. |
+
+Remember that the user chooses the scope: code for the case where
+`canvases()` returns only part of the devlog, and `search` / `range` return
+nothing.
+
+## API usage errors
+
+| Message | Fix |
+|---|---|
+| `devlog.addBlock: a block added inside another needs that block's date` | Pass the parent's day file as `date` with `parentId`. |
+| `devlog.addBlock: a kind only on a canvas it keeps` | Custom kinds are for `managedCanvas` canvases. |
+| `devlog.addBlock: not a kind it may use: …` | Kinds are `^[a-z][a-z0-9-]{0,31}$` and not `note`, `todo`, `task`, `commit` or `done`. |
+| `Not a metadata key: …` | Meta keys are `^[a-z][a-z0-9_-]{0,31}$`, not `id at parent pos kind hidden updated ext`. |
+| `Cannot add an empty block` / `That block is too long` | Markdown must be non-blank and at most 100 000 characters. |
+| `devlog.createCanvas: give it a title` | |
+| `"…" is not one of its node types (contributes.nodeTypes)` | `promote` / `createCanvas` / `updateCanvas` with a type it did not declare. |
+| `…: not a date: …` / `the range ends before it starts` / `at most 400 days at a time` | `activity` and `range` take `YYYY-MM-DD`, in order, at most 400 days apart. |
+| `devlog.managedCanvas: the key is lowercase letters, digits, "_" or "-"` | |
+| `View "…" is not declared in contributes.views` | Declare the view before `views.handle` / `post`. |
+| `Destination "…" is not declared in contributes.destinations` | Declare it before `destinations.register`. |
+| `"…" is not one of its page views` | `ui.openPage` takes a view with `placement: "page"`. |
+| `Not allowed in a path: …` / `Not a relative path: …` / `Not allowed in a file name: …` | `ctx.files` paths are relative and `/`-separated; see [the path rules](Extension-API-Reference#ctxfiles). |
+| `Secret names are lowercase letters, digits, "_" or "-"` | |
+| `Mark the timesheet final before sending it` | `destinations.send` takes only `status: 'final'` sheets. |
+| `… is not ready to send` | The destination's extension is not running, or has not registered that destination. |
+
+## Views
+
+| Symptom / message | Cause and fix |
+|---|---|
+| Blank frame | The extension is not running (views load only while it runs), the `entry` path is wrong, or the page uses an inline `<script>` (blocked by the CSP; load a file). |
+| `The view "…" has no handler yet` | The page called before `ctx.views.handle` ran. Register handlers in `activate`. |
+| `fetch` fails in the page | Views have `connect-src 'none'`. Do network calls in the extension process and expose them with `views.handle`. |
+| `localStorage` throws | Frames are sandboxed without same origin. Keep state in the extension (`ctx.files.local`). |
+| Keyboard shortcuts stop working inside the view | Use `@devlog/ui` (or `@devlog/ui/bridge`), which forwards unused shortcuts to the app with a `key` message. |
+| The status bar item is cut off | Call `devlog.resize({ width })` when content changes; widths are clamped to 24–360 px. |
+| Colours don't follow the theme | Use the theme variables (`var(--fg)`, …), applied by the bridge from the `theme` message. |
+
+## Timeouts
+
+A command has 10 minutes, a view call 60 seconds, a destination preview 2
+minutes and send 10 minutes, a provider 20 seconds. A call that times out
+fails with an error; for long work, return early and report progress with
+`ui.notify` or `views.post`.
diff --git a/wiki/UI-Kit-Reference.md b/wiki/UI-Kit-Reference.md
new file mode 100644
index 0000000..5e58d8b
--- /dev/null
+++ b/wiki/UI-Kit-Reference.md
@@ -0,0 +1,148 @@
+# UI kit reference (`@devlog/ui`)
+
+`@devlog/ui` is for extension **views**: the bridge to the app and your
+extension, React hooks, a handful of components and the app's look. Source:
+[`packages/ui/src`](https://github.com/sdeken/devlog/tree/main/packages/ui/src).
+React 18+ is a peer dependency; bundle both into each view.
+
+| Import | Contents |
+|---|---|
+| `@devlog/ui` | `devlog` (the bridge), `mount`, hooks, components |
+| `@devlog/ui/bridge` | `devlog` only, for pages without React |
+| `@devlog/ui/styles.css` | Design tokens and `dl-*` classes |
+
+Like `@devlog/extension-api`, it is not published to npm; take it from a
+Devlog checkout (see [Extension Quickstart](Extension-Quickstart#types)).
+
+```tsx
+import '@devlog/ui/styles.css'
+import { Button, Empty, mount, useCall } from '@devlog/ui'
+
+function Page(): React.JSX.Element {
+  const { data, error, loading, reload } = useCall<string[]>('items')
+  if (error) return <p className="dl-error">{error}</p>
+  if (loading && !data) return <Empty>Loading…</Empty>
+  return (
+    <div className="dl-page">
+      <h1 className="dl-title">Items</h1>
+      <ul>{data?.map((x) => <li key={x}>{x}</li>)}</ul>
+      <Button onClick={reload}>Reload</Button>
+    </div>
+  )
+}
+mount(<Page />)
+```
+
+## The bridge: `devlog`
+
+Importing the bridge (directly or through `@devlog/ui`) sends `ready`,
+applies the app's theme variables to `:root` as they arrive (and sets
+`data-theme="dark"` or `"light"` on `<html>`), and forwards shortcuts the
+page did not handle (Ctrl/Cmd/Alt + key, F-keys) to the app.
+
+| Member | Description |
+|---|---|
+| `call<T>(method, ...args): Promise<T>` | Ask your extension; arrives at its `ctx.views.handle(viewId, …)` handler. Rejects with the handler's error message. |
+| `onMessage(cb): () => void` | Messages your extension sends with `ctx.views.post`. Returns an unsubscribe function. |
+| `dark: boolean` | Whether the app is in dark mode now. |
+| `onTheme(cb: (dark) => void): () => void` | Called when the theme changes. |
+| `context: ViewContext` | Where the view is shown (see [Views and UI → View context](Views-and-UI#view-context)). |
+| `onContext(cb): () => void` | Called when the context changes. |
+| `resize({ width?, height? }): void` | Ask for a size. Status bar items get their height from the bar; the width may be clamped. |
+| `popover(view, { width?, height? }?): void` | Open one of your popover views, anchored to this view. |
+| `close(): void` | Close this view (a popover). |
+| `open({ canvasId, date?, blockId? }): void` | Show a canvas, or a block's page, in the app. |
+| `command(command): void` | Run one of your commands (with the view's context). |
+
+## `mount(node, opts?)`
+
+Renders a view's root component into `<div id="root">` (made if missing),
+inside `StrictMode`. `opts.slot: true` adds `dl-slot` to `<body>`: a
+transparent, 22 px, one-line body for status bar items.
+
+## Hooks
+
+| Hook | Returns | Description |
+|---|---|---|
+| `useCall<T>(method, args = [], deps = [])` | `{ data, error, loading, reload }` | Calls your extension on mount, when `method` or `deps` change, and on `reload()`. Keeps the last `data` while reloading or after an error. |
+| `useMessages(cb)` | — | Subscribes to `ctx.views.post` messages for the component's lifetime. |
+| `useDark()` | `boolean` | Whether the app is dark; re-renders on change. |
+| `useViewContext()` | `ViewContext` | Where the view is shown; re-renders on change. |
+| `useNow(everyMs = 1000)` | `number` | `Date.now()`, updated on an interval (for running clocks). |
+
+```tsx
+const here = useViewContext().canvasId
+const { data: task } = useCall<Task | null>('task', [here ?? ''], [here])
+```
+
+## Components
+
+### `Button`
+
+A `<button type="button">` with the app's look. Props: every button
+attribute, plus `variant` (`'default' | 'primary' | 'quiet' | 'danger'`) and
+`small`.
+
+```tsx
+<Button variant="primary" onClick={save}>Save</Button>
+<Button small variant="quiet" onClick={() => devlog.close()}>Cancel</Button>
+```
+
+### `Row`, `Stack`
+
+Flex containers (`div` props): `Row` lays out horizontally with an 8 px gap,
+centred; `Stack` vertically with an 8 px gap.
+
+### `Field`
+
+A label and its input: `<Field label="Name"><input className="dl-input" /></Field>`.
+
+### `Empty`
+
+A muted paragraph for empty states: `<Empty>Nothing sent yet.</Empty>`.
+
+### `Menu`
+
+A keyboard-driven pick list: ↑/↓ move, Enter picks, Escape closes the view
+(for popovers), and an optional search box filters.
+
+| Prop | Type | Description |
+|---|---|---|
+| `items` | `MenuEntry[]` | `{ key, label, hint?, onSelect }` |
+| `search` | `boolean` | Show a search box (focused). |
+| `placeholder` | `string` | The search box's placeholder (default "Find…"). |
+| `filterText` | `(item) => string` | Text to filter by (default: the label, when it is a string). |
+| `empty` | `ReactNode` | Shown when nothing matches (default "Nothing here."). |
+| `extra` | `(query) => MenuEntry[]` | Entries added after the filtered ones, from what is typed (a "New …" entry). |
+
+```tsx
+<Menu
+  search
+  placeholder="Start a task…"
+  items={tasks.map((t) => ({ key: t.id, label: t.title, hint: t.path, onSelect: () => void devlog.call('start', t.id).then(() => devlog.close()) }))}
+  extra={(q) => (q ? [{ key: 'new', label: `+ New task "${q}"`, onSelect: () => void devlog.call('newTask', q) }] : [])}
+/>
+```
+
+## CSS
+
+`@devlog/ui/styles.css` sets a box-sizing reset, the body font (14 px, the
+app's font) and colours from the theme variables, and these classes:
+
+| Class | For |
+|---|---|
+| `dl-page` | Padding for a `page` view's content |
+| `dl-title` | A page heading |
+| `dl-row`, `dl-stack`, `dl-spacer` | Horizontal / vertical flex; a flexible spacer |
+| `dl-btn`, `dl-btn-primary`, `dl-btn-quiet`, `dl-btn-danger`, `dl-btn-sm` | Buttons (what `Button` renders) |
+| `dl-input` | Text inputs, selects |
+| `dl-field` | A label with its input (what `Field` renders) |
+| `dl-menu`, `dl-menu-item` (`.is-active`), `dl-menu-hint`, `dl-menu-sep` | Menus (what `Menu` renders) |
+| `dl-table` (`td.num`, `th.num` right-aligned) | Tables |
+| `dl-badge` (`.is-accent`) | Small labels |
+| `dl-dot` (`.is-busy`, `.is-warn`) | A status dot |
+| `dl-muted`, `dl-empty`, `dl-error` | Muted text, empty states, errors |
+| `body.dl-slot` | A status bar item's body |
+
+Theme variables (`--bg`, `--fg`, `--accent`, …) are listed in
+[Views and UI → Theme variables](Views-and-UI#theme-variables).
diff --git a/wiki/Views-and-UI.md b/wiki/Views-and-UI.md
new file mode 100644
index 0000000..731c956
--- /dev/null
+++ b/wiki/Views-and-UI.md
@@ -0,0 +1,246 @@
+# Views and UI
+
+Views (API 1.5) are HTML pages from an extension's package that the app
+shows in sandboxed frames: a page in the main area, an item in the status
+bar, a popover, or a control beside a canvas's title. A view cannot reach the
+network, the app's window or the extension's process directly; it talks to
+its extension **through the app**, by `postMessage`.
+
+```
+┌──────── Devlog window ────────┐        ┌──── extension process ────┐
+│  <iframe sandbox=allow-scripts│        │                            │
+│   src=devlog-ext://…/x.html>  │        │ ctx.views.handle('x', fn)  │
+│     devlog.call('status') ────┼──IPC──►│   fn('status', [])         │
+│     ◄── reply ────────────────┼────────┤   return {...}             │
+│     ◄── message ──────────────┼────────┤ ctx.views.post('x', data)  │
+│     ◄── theme, context ───────┤        │                            │
+└───────────────────────────────┘        └────────────────────────────┘
+```
+
+Other ways for an extension to show things without a view:
+`ctx.ui.notify`, `confirm`, `pick`, `app.setTrayLabel`, `ui.highlight` and
+blocks it writes. See [Extension API Reference](Extension-API-Reference#ctxui).
+
+## Declaring views
+
+```json
+"contributes": {
+  "views": [
+    { "id": "summary", "title": "Summary", "entry": "dist/views/summary.html", "placement": "page", "icon": "Σ" },
+    { "id": "status", "title": "Time tracking", "entry": "dist/views/status.html", "placement": "statusbar" },
+    { "id": "picker", "title": "Start a task", "entry": "dist/views/picker.html", "placement": "popover" },
+    { "id": "header", "title": "Start or stop this task", "entry": "dist/views/header.html", "placement": "canvasHeader", "nodeType": "task" }
+  ]
+}
+```
+
+Field rules are in [Extension Manifest → views](Extension-Manifest#views-15).
+
+## Placements
+
+| Placement | Since | Where | Size | Context it gets |
+|---|---|---|---|---|
+| `page` | 1.5 | Listed in the sidebar and quick switcher with the app's views; fills the main area. Open it from code with `ctx.ui.openPage(id)` (1.7). | The main area | — |
+| `statusbar` | 1.5 | A slot in the status bar. | 22 px high; asks for a width with `resize`, clamped to 24–360 px | The canvas (and block page) on screen |
+| `popover` | 1.5 | Opened by another of its views with `popover`, anchored to that view; closes on Escape, a click outside, or `close`. | Default 320 × 360; width clamped to 160–560 px, height to 640 px | The opener's context |
+| `canvasHeader` | 1.6 | Beside a canvas's title, on every canvas or only those of `nodeType`. | 26 px high; starts 120 px wide and asks for a width with `resize`, clamped to 24–480 px | That canvas |
+
+The composer (note box) is not shown on extension pages.
+
+## How a view is served
+
+- URL: `devlog-ext://<the devlog.json key, as hex>/<file>`, only from the
+  extension's own folder and **only while the extension runs**.
+- Served types: `.html`, `.htm`, `.js`, `.mjs`, `.css`, `.json`, `.svg`,
+  `.png`, `.jpg`, `.woff2`. Anything else is a 404.
+- The frame is `sandbox="allow-scripts"` (no same origin: no cookies,
+  `localStorage` or access to the parent), with `referrerpolicy=no-referrer`.
+- Content Security Policy:
+
+  ```
+  default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline';
+  img-src 'self' data:; font-src 'self' data:; connect-src 'none';
+  frame-src 'none'; form-action 'none'; base-uri 'none'
+  ```
+
+  So: scripts from your package only (no inline `<script>`), no `fetch` or
+  WebSocket, no frames, no form submission. Put network calls in the
+  extension process and expose them through `views.handle`.
+
+## Answering a view
+
+In the extension:
+
+```js
+ctx.views.handle('status', async (method, args) => {
+  switch (method) {
+    case 'status': return clock.status()
+    case 'start':  await clock.start(String(args[0])); return clock.status()
+    default: throw new Error(`No method ${method}`)
+  }
+})
+
+// Push updates to every open copy of the view.
+clock.onChange((st) => ctx.views.post('status', st))
+```
+
+- One handler per view id (a later `handle` replaces it). One handler may
+  serve several views: `for (const v of ['status', 'header']) ctx.views.handle(v, handler)`.
+- A thrown error becomes a rejected `devlog.call` in the page, with the
+  error's message.
+- Calls time out after 60 seconds. A call made before the handler is
+  registered fails with `The view "…" has no handler yet`.
+
+## Writing a view with `@devlog/ui`
+
+`@devlog/ui` is a small React kit: the bridge, hooks, a few components and
+the app's look. Bundle it into the view's script. Full reference:
+[UI Kit Reference](UI-Kit-Reference).
+
+`src/views/status.tsx`:
+
+```tsx
+import '@devlog/ui/styles.css'
+import { useLayoutEffect, useRef, useState } from 'react'
+import { Button, devlog, mount, useCall, useMessages, useViewContext } from '@devlog/ui'
+
+interface Status { active: string | null; label: string | null }
+
+function StatusItem(): React.JSX.Element {
+  const initial = useCall<Status>('status')
+  const [st, setSt] = useState<Status | undefined>()
+  useMessages((d) => setSt(d as Status))            // ctx.views.post('status', …)
+  const shown = st ?? initial.data
+  const here = useViewContext().canvasId            // the canvas on screen
+
+  // Ask for the width the content needs.
+  const ref = useRef<HTMLDivElement>(null)
+  useLayoutEffect(() => {
+    if (ref.current) devlog.resize({ width: Math.ceil(ref.current.scrollWidth) + 2 })
+  })
+
+  return (
+    <div className="dl-row" ref={ref}>
+      <span className="dl-muted">{shown?.label ?? 'No active task'}</span>
+      {here && <Button small variant="primary" onClick={() => void devlog.call('start', here)}>Start</Button>}
+      <Button small variant="quiet" onClick={() => devlog.popover('picker', { width: 340, height: 380 })}>▾</Button>
+    </div>
+  )
+}
+
+mount(<StatusItem />, { slot: true }) // slot: the status bar's styling
+```
+
+Build each view to one script and one stylesheet next to an HTML file.
+esbuild, as `scripts/build-builtins.mjs` does for the built-ins:
+
+```sh
+npx esbuild src/views/status.tsx --bundle --platform=browser --format=iife \
+  --target=chrome120 --jsx=automatic --minify \
+  --define:process.env.NODE_ENV='"production"' \
+  --outfile=dist/views/status.js
+```
+
+`dist/views/status.html`:
+
+```html
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>Time tracking</title>
+<link rel="stylesheet" href="status.css">
+</head>
+<body>
+<div id="root"></div>
+<script src="status.js"></script>
+</body>
+</html>
+```
+
+## Writing a view without React
+
+Any page can speak the protocol. Import `@devlog/ui/bridge` alone, or send
+the messages yourself:
+
+```js
+// view.js (loaded with <script src="view.js">; inline scripts are blocked)
+let next = 1
+const waiting = new Map()
+const send = (msg) => window.parent.postMessage({ devlog: 1, ...msg }, '*')
+
+window.addEventListener('message', (ev) => {
+  if (ev.source !== window.parent || ev.data?.devlog !== 1) return
+  const m = ev.data
+  if (m.type === 'theme') for (const [k, v] of Object.entries(m.vars)) document.documentElement.style.setProperty(k, v)
+  if (m.type === 'reply') { const w = waiting.get(m.id); waiting.delete(m.id); m.ok ? w?.resolve(m.value) : w?.reject(new Error(m.error)) }
+  if (m.type === 'message') render(m.data)
+})
+
+const call = (method, ...args) => new Promise((resolve, reject) => {
+  const id = next++
+  waiting.set(id, { resolve, reject })
+  send({ type: 'call', id, method, args })
+})
+
+send({ type: 'ready' })
+call('status').then(render)
+```
+
+## Message protocol
+
+Types: `@devlog/extension-api/view`. Every message carries `devlog: 1`.
+Messages from anything but `window.parent` should be ignored.
+
+### From the page to the app (`ViewToApp`)
+
+| `type` | Fields | Since | Meaning |
+|---|---|---|---|
+| `ready` | — | 1.5 | The page is listening. The app answers with `theme`, then `context`. |
+| `call` | `id`, `method`, `args` | 1.5 | Ask the extension (its `views.handle` handler). Answered by `reply` with the same `id`. |
+| `resize` | `width?`, `height?` | 1.5 | The size the page would like. Status bar and header items get their height from the bar. |
+| `popover` | `view`, `width?`, `height?` | 1.5 | Open one of the extension's `popover` views, anchored to this one. |
+| `close` | — | 1.5 | Close this view (a popover). |
+| `open` | `canvasId`, `date?`, `blockId?` | 1.5 | Show a canvas, or a block's page, in the app. |
+| `command` | `command` | 1.5 | Run one of the extension's commands, with `source: 'view'` and the view's context (1.6). |
+| `key` | `key`, `code`, `ctrlKey`, `metaKey`, `altKey`, `shiftKey` | 1.7 | A shortcut the page did not use (Ctrl, Alt or Cmd with a key; F-keys), so Ctrl+K and the like still reach the app. `@devlog/ui/bridge` sends these for you. |
+
+### From the app to the page (`AppToView`)
+
+| `type` | Fields | Since | Meaning |
+|---|---|---|---|
+| `theme` | `vars`, `dark` | 1.5 | The app's colours as CSS custom properties, and whether it is dark. Sent after `ready`, on load, and whenever the theme changes. |
+| `reply` | `id`, `ok`, `value?`, `error?` | 1.5 | The answer to a `call`. |
+| `message` | `data` | 1.5 | Something the extension sent with `ctx.views.post`. |
+| `context` | `context: ViewContext` | 1.6 | Where the view is shown; sent after `theme`, and again when it changes. |
+
+### Theme variables
+
+`--bg`, `--bg-2`, `--bg-3`, `--fg`, `--fg-muted`, `--border`,
+`--border-strong`, `--accent`, `--accent-fg`, `--warn`, `--danger`, `--ok`,
+`--link`, `--code-bg`, `--shadow`, `--mono`, `--sans`, `--font`. Use them in
+your CSS (`color: var(--fg)`) and the view follows the user's theme and
+light/dark mode. `@devlog/ui/styles.css` has defaults for the moment before
+the first `theme` message.
+
+### View context
+
+| Placement | `context` |
+|---|---|
+| `canvasHeader` | `{ canvasId }` of the canvas it sits on |
+| `statusbar` | The canvas on screen, and `date` + `blockId` when a block page is on screen |
+| `popover` | The context of the view that opened it |
+| `page` | `{}` |
+
+Commands run from a view (`command` message) get the same context.
+
+## Tips
+
+- Keep state in the extension process and push it with `views.post`; views
+  come and go (a popover closes, the user navigates).
+- Several copies of a view can be open at once; `post` reaches them all.
+- Status bar items: call `resize` whenever the content changes width, and use
+  `mount(…, { slot: true })` (or `body.dl-slot`) for a transparent,
+  one-line, 22 px body.
+- A view loads only while its extension runs; if the extension is stopped
+  the frame shows nothing.
diff --git a/wiki/_Footer.md b/wiki/_Footer.md
new file mode 100644
index 0000000..26adf3c
--- /dev/null
+++ b/wiki/_Footer.md
@@ -0,0 +1 @@
+Devlog 0.18.0 · extension API 1.7.0 · storage format 4 · [Repository](https://github.com/sdeken/devlog) · [Design notes](https://github.com/sdeken/devlog/blob/main/docs/DESIGN.md)
diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md
new file mode 100644
index 0000000..f2d6698
--- /dev/null
+++ b/wiki/_Sidebar.md
@@ -0,0 +1,28 @@
+**[Home](Home)**
+
+**Using Devlog**
+- [Getting Started](Getting-Started)
+- [Concepts](Concepts)
+
+**Writing extensions**
+- [Overview](Extensions-Overview)
+- [Quickstart](Extension-Quickstart)
+- [Manifest](Extension-Manifest)
+- [API Reference](Extension-API-Reference)
+- [Types](Extension-Types)
+- [Views and UI](Views-and-UI)
+- [UI Kit Reference](UI-Kit-Reference)
+- [Timesheet Destinations](Timesheet-Destinations)
+- [Activity and Time Data](Activity-and-Time-Data)
+- [Sandbox and Permissions](Sandbox-and-Permissions)
+- [Testing](Testing-Extensions)
+- [Built-in Extensions](Built-in-Extensions)
+- [API Versions](API-Versions)
+- [Troubleshooting](Troubleshooting-Extensions)
+
+**Devlog internals**
+- [Architecture](Architecture)
+- [Storage Format](Storage-Format)
+- [Core Library](Core-Library)
+- [Extension Host Protocol](Extension-Host-Protocol)
+- [Development](Development)