@overcrow/mcp 0.0.0 → 0.1.0

package/dist/content/docs/en/forms.md

@@ -0,0 +1,328 @@
+# Forms and write intents
+
+A PlayerVox OverCrow widget takes input through controls that OverCrow
+draws and edits itself: buttons, toggles, checkboxes, sliders, drop-down
+lists, text fields. The logic hears about them through events. A `form`
+groups controls and submits them together, and a form bound to a **write
+intent** is how a widget lets the user write to their notes, publish a
+rating or send a chat message, without the text ever passing through the
+widget's code.
+
+Widgets receive input only in OverCrow's Interactive mode. In Passive mode
+a click goes through the widget to the game: hide or disable what cannot be
+used, as the built-ins do with `host.mode`.
+
+## Controls
+
+| Element | Value | Events |
+| --- | --- | --- |
+| `button` | none | `activate` |
+| `toggle`, `checkbox` | `checked` | `change` |
+| `slider` | `value`, between `min` and `max` | `input` while dragging, `change` on release |
+| `select` with `option` children | `value` of the chosen option | `change` |
+| `field` | one line of text | `input` at each edit, `change` on Enter or when the focus leaves, `submit` on Enter |
+| `textarea` | several lines of text | `input`, `change`, `submit` on Ctrl+Enter |
+
+Each takes a `label`, its accessible name, and `disabled`. Their attributes
+are in [elements and attributes](elements.md).
+
+<!-- source: docs/content/examples/countdown/view.ocml -->
+```xml
+    <select class="duration" value={minutesValue(state.minutes)} label={t("duration")} disabled={state.running} on:change={setMinutes}>
+      <for each={state.durations} as="minutes" key={minutes}>
+        <option value={minutesValue(minutes)}>{t("minutes", { count: minutes })}</option>
+      </for>
+    </select>
+```
+
+<!-- source: docs/content/examples/countdown/logic.ts -->
+```ts
+export function setMinutes(event: { value: unknown }): void {
+  const minutes = Number(event.value);
+  if (state.durations.includes(minutes)) {
+    state.minutes = minutes;
+    state.remainingMs = total(minutes);
+  }
+}
+```
+
+The view binds the control to the state (`value={…}`, `checked={…}`), and
+the handler writes the new value back. The detail of `input` and `change`
+is `{ value }`: a boolean for a toggle or a checkbox, a number for a
+slider, text for the others.
+
+<!-- source: docs/content/examples/countdown/view.ocml -->
+```xml
+    <toggle class="repeat" label={t("repeat")} tooltip={t("repeat")} checked={state.repeat} on:change={setRepeat}/>
+```
+
+### Text fields
+
+OverCrow edits the text of a `field` or a `textarea` itself: the caret, the
+selection, copy and paste, and input methods for languages that compose
+characters. The logic receives a copy of the text in each `input` event.
+
+<!-- source: widgets/warframe-market/view.ocml -->
+```xml
+      <field class="query" label={t("search-field")} value={state.query} placeholder={t("placeholder")} max-length="256" on:input={search}/>
+```
+
+<!-- source: widgets/warframe-market/logic.ts -->
+```ts
+export function search(detail: { value: unknown }): void {
+  state.query = typeof detail.value === "string" ? detail.value : "";
+  state.results = searchItems(items, lowered, state.query);
+  state.detail = null;
+  state.loadingOrders = false;
+  state.refreshing = false;
+  state.copy = null;
+  if (state.error === "orders_unavailable") {
+    state.error = null;
+  }
+  selection += 1;
+  stopRefresh();
+  saveQuery();
+}
+```
+
+Binding `value` replaces what the field holds: bind it to the state your
+`input` handler writes, as above, or leave it out and only listen.
+`max-length` bounds the text in bytes, and `placeholder` shows a hint while
+the field is empty.
+
+A field also sends `keydown` when you ask for it, with the key and its
+modifiers, for shortcuts such as Escape to cancel. Keys that OverCrow
+reserves (Tab to move the focus, its own shortcuts, a composition in
+progress) are not delivered.
+
+### The focus when an editor opens
+
+The logic cannot move the keyboard focus. A `field` or a `textarea` that
+carries `autofocus` takes it by itself when it appears while the logic
+handles a user action: a click on an Edit button that opens an editor puts
+the caret in the field, after its text, as a click in it would.
+
+<!-- source: widgets/notes/view.ocml -->
+```xml
+        <field class="title-field" name="title" autofocus placeholder={t("title-hint")} label={t("title-hint")} on:input={titleInput(editor.key, event.value)} on:keydown={keyed(editor.key, event.key, event.ctrl)}/>
+```
+
+OverCrow gives that focus only when the element appears during a
+[user action](services.md#calls-that-need-a-user-action), in Interactive
+mode, in the widget the user acted on; when several such elements appear
+together, the first one of the view takes it. An element that appears when
+the widget starts, from a timer or from the answer of a service (after an
+`await` in the handler of the click too) does not take the focus, and
+neither does an element that was already shown: `autofocus` is read when
+the element appears. Give it to one field of an editor, and not to a field
+that appears while the user types, such as a new row of a list.
+
+## Forms
+
+A `form` groups controls and gives them one `submit` event. It is
+submitted by Enter in a `field`, by Ctrl+Enter in a `field` or a
+`textarea`, or by activating a button with the `submit` attribute.
+
+<!-- source: widgets/twitch-chat/view.ocml -->
+```xml
+      <form class="selector" on:submit={join}>
+        <field class="input channel" max-length="26" autofocus placeholder={t("channel-name")} label={t("channel-name")} on:input={channelTyped(event.value)}/>
+        <button class="action" submit disabled={!canJoin(state)}>
+          <text class="action-label">{t("join")}</text>
+        </button>
+      </form>
+```
+
+<!-- source: widgets/twitch-chat/logic.ts -->
+```ts
+export function join(): void {
+  const channel = normalizeChannel(state.channelDraft);
+  if (channel !== null) {
+    joinChannel(channel);
+  }
+}
+```
+
+This form has no intent: its `submit` handler reads what the `input`
+handler kept in the state, and calls a service. `submit` is a user action,
+so the handler may call a service that needs one
+(`twitch.chat.join` here).
+
+A form keeps what the user entered for as long as it stays in the view.
+Hide it with `display: none` to keep a draft; remove it from the view to
+discard one. To start over with empty fields, give the form a new key in a
+`for`: a new key is a new form.
+
+## Forms that write user data
+
+Three things a widget can do write text that the user typed into the
+user's own data: saving a note, publishing a PlayerVox rating with its
+review, and sending a Twitch chat message. They are not service calls. A
+form with an `intent` attribute sends them:
+
+<!-- source: widgets/twitch-chat/view.ocml -->
+```xml
+    <form class={composerClass(state)} intent="twitch.chat.send" target={replyTarget(state)} on:submit={submitted(event.outcome, event.error)}>
+      <if test={state.reply}>
+        <box class="replying">
+          <text class="replying-label">{replyingTo(state)}</text>
+          <button class="icon-button small" label={t("cancel-reply")} tooltip={t("cancel-reply")} on:activate={cancelReply}>
+            <icon name="x"/>
+          </button>
+        </box>
+      </if>
+      <if test={state.sendError != ""}>
+        <text class="error">{t(state.sendError)}</text>
+      </if>
+      <box class="compose">
+        <field class="input message-field" name="message" max-length="500" placeholder={t(composerHint(state))} label={t("message-label")} disabled={!state.canSend} on:input={drafted(event.value)} on:keydown={keyed(event.key)}/>
+        <if test={sendMark(state) != ""}>
+          <text class={sendMarkClass(state)}>{t(sendMark(state))}</text>
+        </if>
+        <button class="action" submit disabled={!canSubmit(state)} on:activate={sendPressed}>
+          <text class="action-label">{t("send")}</text>
+        </button>
+      </box>
+    </form>
+```
+
+When the user submits such a form, **OverCrow reads the values of the
+form's own controls and sends them itself**. The widget's logic never
+supplies the text, so a widget cannot write something the user did not
+type, and cannot submit without the user: the form goes only on a user
+action, in Interactive mode, with the capability granted.
+
+What this changes for the view and the logic:
+
+- **The controls belong to OverCrow.** The `field`, `textarea` and `slider`
+  controls of the form take no `value`: `overcrow-widget check` refuses it
+  (`view.bound_value`), and OverCrow stops a widget that sets one at run
+  time. Their `name` attribute says which field of the intent each one is.
+- **OverCrow fills them** where the intent says so: the note's title, body
+  and checklist, the user's published rating. A fill sends the control's
+  `input` event with the value, so the logic knows what is shown; that
+  event is not a user action.
+- **The logic follows through `input` events**, to show a counter or to
+  enable the button, and may disable the controls.
+- **The outcome arrives in the form's `submit` event**: `event.outcome` is
+  `accepted`, `rejected` (with the [error code](services.md#errors) in
+  `event.error`) or `cancelled`. A form without an intent gives
+  `submitted`.
+
+<!-- source: widgets/playervox-rating/view.ocml -->
+```xml
+      <slider class="criterion-slider" name="gameplay" min="0" max="100" step="1" label={t("gameplay")} disabled={!editable(state)} on:input={scored("gameplay", event.value)}/>
+```
+
+<!-- source: widgets/playervox-rating/logic.ts -->
+```ts
+export function scored(key: CriterionKey, value: number): void {
+  state[key] = value;
+  edited();
+}
+```
+
+<!-- source: widgets/playervox-rating/logic.ts -->
+```ts
+export function submitted(outcome: string, error: ServiceErrorPayload | undefined): void {
+  state.pending = Math.max(0, state.pending - 1);
+  if (state.pending === 0) {
+    answer?.cancel();
+    answer = null;
+  }
+  if (outcome === "accepted") {
+    // The subscription sends the stored rating; nothing is read again.
+    state.saved = true;
+    state.error = "";
+  } else if (outcome !== "cancelled") {
+    state.error = errorKey(error?.code ?? null);
+  }
+}
+```
+
+A write does not change what a subscription says by itself: after an
+accepted rating, `playervox.rating.subscribe` delivers the stored rating,
+and the widget shows that.
+
+### The intents
+
+<!-- generated:write-intents -->
+### `notes.save`
+
+Capability `notes.write`; `target` attribute required (note ID; the host fills the bound controls from that note). Enter in a `field` of the form moves the focus to its next `field` or `textarea` and does not submit; Ctrl+Enter and a `submit` button do.
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `title` | text ≤ 96 bytes | yes | `field`; saved trimmed, and not empty. |
+| `body` | text ≤ 8 KiB | no | `textarea`; saved as written. |
+| `item` | list of `NoteItem` ≤ 64 | no | One `field` per checklist row, in order, each ≤ 256 bytes. The host remembers which item it filled each field with: a row keeps that item's ID and check whichever rows the widget removes or moves, and a field that appeared since is a new, unchecked item. Rows are saved trimmed; an empty row is dropped. A note saved as it is stored is accepted without a write. |
+
+### `playervox.rating.publish`
+
+Capability `playervox.rating.write`; `target` attribute refused.
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `gameplay` | integer 0 to 100 | yes | `slider`; filled from the user's rating, 50 before the first one. |
+| `art` | integer 0 to 100 | yes | `slider`; filled like `gameplay`. |
+| `tech` | integer 0 to 100 | yes | `slider`; filled like `gameplay`. |
+| `review` | text ≤ 2000 characters | no | `textarea`; filled from the published review. An unchanged review is not sent again; an emptied one removes it. |
+
+### `twitch.chat.send`
+
+Capability `twitch.chat.compose`; `target` attribute optional (ID of the message replied to).
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `message` | text ≤ 500 characters | yes | `field`; the host clears it after a successful send. |
+<!-- /generated:write-intents -->
+
+`target` is the form's attribute that names the object written: the note's
+ID for `notes.save`, the ID of the message replied to for
+`twitch.chat.send`.
+
+### Several rows of one field
+
+The `notes.save` intent takes one `item` field per checklist row. The
+logic decides which rows the form has, with a `for`; OverCrow fills each
+row's field from the stored note and remembers which checklist entry it
+put there. A row that the logic removes or moves keeps its entry, and a
+row added since is a new entry.
+
+<!-- source: widgets/notes/view.ocml -->
+```xml
+          <for each={editor.rows} as="row" key={row.key}>
+            <box class="row">
+              <if test={rowStored(state, editor, row)}>
+                <checkbox class="row-check" checked={rowChecked(state, editor, row)} label={rowLabel(row)} on:change={check(editor.note, row.id, event.value)}/>
+              </if>
+              <else>
+                <icon class="row-new" name="circle"/>
+              </else>
+              <field class="row-field" name="item" placeholder={rowHint(editor, row)} label={t("item-hint")} on:input={rowInput(editor.key, row.key, event.value)} on:keydown={keyed(editor.key, event.key, event.ctrl)}/>
+```
+
+In that form, Enter moves to the next field instead of submitting;
+Ctrl+Enter or the `submit` button saves.
+
+## Confirmations
+
+Two services delete user data: `notes.delete` and `journal.delete`. They
+are ordinary calls that need a user action, and OverCrow then asks the
+user to confirm in a dialog that it draws itself, outside the widget. The
+call resolves when the user confirms and fails with `cancelled` when they
+decline. Do not draw your own "Are you sure?": OverCrow's is the one that
+counts.
+
+## Checklist for a form
+
+- Every control has a `label`.
+- Buttons that cannot act are `disabled`, and nothing that needs input
+  shows in Passive mode.
+- The `submit` handler handles a refusal: `not_connected` when the account
+  is signed out, `busy` when the user sends too fast, `unavailable`.
+- A form bound to an intent has no `value` on its text fields and
+  sliders, and every named control is a field of the intent.
+- Test it with a scenario: `text` steps type into the focused field,
+  `key` steps press Enter, and `expect.intents` checks exactly what
+  OverCrow sent. See [testing a widget](testing.md#steps).

package/dist/content/docs/en/guide.md

@@ -0,0 +1,253 @@
+# Creator guide
+
+This guide takes a PlayerVox OverCrow widget from an empty directory to a
+submission: create a project, edit its view, style and logic, run it in
+OverCrow, test it, package it and submit it. Each step links to the page
+that covers it in full.
+
+To work with an AI assistant instead, add OverCrow's MCP server to it: see
+[MCP](mcp.md).
+
+## 1. Install the tools
+
+- **`overcrow-widget`**, the widget CLI, one binary for Linux and Windows.
+  See [installing the CLI](cli.md#installing).
+- **Node.js 22 or later** and npm, so that `check` can type-check your
+  logic with the project's own TypeScript and the SDK from npm. The CLI checks and packages without it, but
+  warns that types were not checked.
+- **OverCrow**, to run the widget while you write it.
+
+`overcrow-widget doctor` tells what your setup has and lacks.
+
+## 2. Create a project
+
+```sh
+overcrow-widget init my-counter --template counter
+cd my-counter
+npm install
+```
+
+`npm install` brings TypeScript and `@overcrow/sdk` 1.0.0, named in the
+project's `package.json`.
+
+The templates are `blank`, `counter`, `list` and `chart`. The ID defaults to
+`com.example.<dir>`: pass `--id` with a reverse-DNS name you control
+(`com.playervox.*` is reserved). [Files of a project](cli.md#files-of-a-project)
+lists every file and says which ones are packaged;
+[the SDK types](cli.md#the-sdk-types) says how to add the SDK to another
+project.
+
+## 3. The view
+
+`view.ocml` is markup: elements, attributes, `{…}` expressions bound to the
+state, and `on:<event>` handlers that call functions exported by the logic.
+
+<!-- source: templates/counter/view.ocml -->
+```xml
+<box class="counter">
+  <text class="value">{state.count}</text>
+  <box class="actions">
+    <button class="step" label={t("decrement")} on:activate={decrement}>
+      <icon name="minus"/>
+    </button>
+    <button class="step" label={t("increment")} on:activate={increment}>
+      <icon name="plus"/>
+    </button>
+  </box>
+</box>
+```
+
+The view also has `if`, `for` with a mandatory key, and local components:
+see [the view](view.md). Every element and attribute is in
+[elements and attributes](elements.md).
+
+## 4. The style
+
+`style.ocss` is a bounded subset of CSS: class, element, descendant and
+child selectors, the `:hover`, `:active`, `:focus`, `:disabled` and
+`:checked` states, flex and grid layout, and the theme's design tokens as
+`var(--…)`, which follow the user's light or dark theme.
+
+<!-- source: templates/counter/style.ocss -->
+```css
+.step {
+  width: var(--icon-button-size);
+  height: var(--icon-button-size);
+  border-radius: var(--radius-md);
+  background: var(--color-surface-raised);
+}
+```
+
+<!-- source: templates/counter/style.ocss -->
+```css
+.step:hover {
+  background: var(--color-surface-hover);
+}
+```
+
+There is no `@media`, `@import`, `url()` or `calc()`: an unknown
+property or selector is an error, not a silent no-op. See
+[the style](style.md) and [style properties and tokens](style-properties.md).
+
+## 5. The logic
+
+`logic.ts` owns the state. Declare its type once, mutate it in your
+handlers, and the view follows: after each turn the VM evaluates the view
+again and sends only what changed.
+
+<!-- source: templates/counter/logic.ts -->
+```ts
+import { initState } from "@overcrow/sdk";
+
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    count: number;
+  }
+}
+```
+
+<!-- source: templates/counter/logic.ts -->
+```ts
+export function increment(): void {
+  state.count += 1;
+}
+```
+
+The logic runs in a sandboxed VM, not in a browser: there is no DOM,
+`fetch`, `setTimeout`, `console` or `Intl`. The SDK provides timers,
+services, formatting helpers for times and numbers in the user's regional
+format, messages and drawing. See [the logic](logic.md) and the
+[SDK reference](sdk.md).
+
+## 6. Messages
+
+`t("key")` in the view or the logic reads `locales/en.json` or
+`locales/fr.json` for the user's language, and fills `{name}` parameters.
+
+<!-- source: templates/counter/locales/en.json -->
+```json
+{
+  "decrement": "Decrease",
+  "increment": "Increase"
+}
+```
+
+Provide both files or neither, with the same keys. See
+[messages](logic.md#messages).
+
+## 7. Check
+
+```sh
+overcrow-widget check
+```
+
+`check` runs the same validators as OverCrow: manifest, view, style,
+locales, a lint of the logic against what the VM runs, the project's
+TypeScript, and a package built in memory and read back. Each problem has a
+stable code, a position and a help line; see
+[diagnostics](cli.md#diagnostics).
+
+## 8. Run it in OverCrow
+
+```sh
+overcrow-widget dev
+```
+
+`dev` sends the widget to the OverCrow overlay running on your machine and
+reloads it each time you save. OverCrow offers this only when it was
+started with development installs allowed (`OVERCROW_WIDGET_DEVELOPMENT=1`;
+`overcrow-widget doctor` prints the commands). The widget shows an
+**Unverified · development package** marker; its declared permissions are
+granted for the session only, and nothing is stored. `log.info(…)` from your
+logic prints in the terminal. See
+[the development channel](dev-channel.md).
+
+## 9. Test it
+
+Two kinds of tests, both described in [testing a widget](testing.md):
+
+- unit tests of the logic with `@overcrow/sdk/testing`, which runs your
+  module with virtual time and simulated services;
+- scenarios played by `overcrow-widget test` in OverCrow's headless
+  runtime: the real VM and renderer, services answered by fixtures, and
+  images compared with references.
+
+<!-- source: templates/counter/tests/example.scenario.json -->
+```json
+  "host": { "mode": "interactive" },
+  "steps": [
+    { "expect": { "state": "running", "text": ["0"], "image": "initial" } },
+    { "pointer": { "click": { "label": "Increase" } } },
+    { "expect": { "text": ["1"], "noText": ["0"], "image": "increased", "fault": "none" } }
+  ]
+```
+
+```sh
+overcrow-widget test
+```
+
+## 10. Ask for what you need
+
+A widget gets nothing by default. To call an API, keep data or read game
+information, declare it in `manifest.json`; the user consents in the
+Control Center before the widget gets it. A network rule names one HTTPS origin, one method and one
+complete path, with typed parameters:
+
+<!-- source: docs/content/examples/weather/manifest.json -->
+```json
+  "permissions": {
+    "network": [
+      {
+        "origin": "https://api.example.com",
+        "method": "GET",
+        "path": "/v1/forecast/{city}",
+        "pathParams": { "city": { "type": "slug", "maxLength": 32 } },
+        "queryParams": {
+          "units": { "type": "enum", "values": ["metric", "imperial"], "required": true }
+        }
+      }
+    ],
+    "storage": true
+  },
+```
+
+<!-- source: docs/content/examples/weather/logic.ts -->
+```ts
+    const url = `https://api.example.com/v1/forecast/${state.city}?units=${state.units}`;
+    const { status, body } = await http.fetch(url, { as: "json" });
+```
+
+Game and system data come from subscriptions (`fps.subscribe`,
+`media.subscribe`…), which update your state until you cancel them. See
+[services and permissions](services.md) for what each permission allows,
+and [security](security.md) for what a widget can never do. The complete
+example is in
+[`docs/content/examples/weather`](../examples/weather/).
+
+## 11. Package
+
+```sh
+overcrow-widget package
+overcrow-widget inspect dist/com.example.my-counter-0.1.0.ocpkg
+```
+
+`package` writes a deterministic `.ocpkg` to `dist/`: the same sources and
+CLI version give the same bytes on every system. `inspect` shows what a
+package holds and asks for, as a reviewer sees it. A package installed
+locally stays unverified; users get widgets from the signed catalog. See
+[the package](package.md).
+
+## 12. Submit
+
+Add a `listing.json` with the marketplace text, run the admission yourself,
+then open a pull request that adds your widget under `widgets/<dir>/` on the
+`candidate` branch of the
+[public repository](https://github.com/Valhallab/playervox-overcrow-releases):
+
+```sh
+overcrow-widget admit
+```
+
+`admit` runs exactly the checks of the marketplace CI. What happens next,
+from review to the signed catalog, is in
+[publishing and review](publishing.md).

package/dist/content/docs/en/index.md

@@ -0,0 +1,85 @@
+# Build widgets for PlayerVox OverCrow
+
+A PlayerVox OverCrow widget is a small package that the overlay draws over
+your game: a clock, a frame-rate counter, a checklist, a chat. You describe
+its view in markup, style it with a small subset of CSS, and write its logic
+in TypeScript against `@overcrow/sdk`. The `overcrow-widget` command-line
+tool checks, tests and packages it; the signed catalog brings it to users.
+
+Every built-in widget of OverCrow is written this way, with the same public
+SDK, package format and sandbox as yours. Their sources are the
+[reference widgets](widgets.md).
+
+## What a widget is made of
+
+| File | Role | Page |
+| --- | --- | --- |
+| `manifest.json` | Identity, version, names, size rules, the options menu and the permissions the widget asks for. | [The manifest](manifest.md) |
+| `view.ocml` | The view: elements such as `box`, `text`, `button`, `list` or `chart`, bound to the state with `{…}` expressions. | [The view](view.md) |
+| `style.ocss` | Optional style: flex and grid layout, colours, borders, typography, with the theme's design tokens. | [The style](style.md) |
+| `logic.ts` | The logic: the state, the event handlers, timers and calls to services. | [The logic](logic.md) |
+| `locales/en.json`, `locales/fr.json` | Optional messages in English and French. | [Messages](logic.md#messages) |
+| `LICENSE` | The license of your widget. | [The package](package.md) |
+
+The view and the logic meet like this: the view reads `state.count` and
+calls the handlers the logic exports.
+
+<!-- source: templates/counter/view.ocml -->
+```xml
+<box class="counter">
+  <text class="value">{state.count}</text>
+  <box class="actions">
+    <button class="step" label={t("decrement")} on:activate={decrement}>
+      <icon name="minus"/>
+    </button>
+    <button class="step" label={t("increment")} on:activate={increment}>
+      <icon name="plus"/>
+    </button>
+  </box>
+</box>
+```
+
+<!-- source: templates/counter/logic.ts -->
+```ts
+const state = initState({ count: 0 });
+
+export function increment(): void {
+  state.count += 1;
+}
+```
+
+## How a widget runs
+
+- The logic runs in its own small JavaScript VM, in its own sandboxed
+  process. It has no DOM, no file system, no network and no access to other
+  widgets; it reaches OverCrow only through the SDK.
+- After each event, timer tick or service answer, the VM evaluates the view
+  again and sends OverCrow only what changed. OverCrow lays out and paints
+  the widget itself: no web engine is involved.
+- Everything that reaches the outside (network, storage, clipboard, game
+  data) is a service of OverCrow, which checks the widget's declared and
+  consented permissions at each call. See
+  [services and permissions](services.md).
+
+These pages call OverCrow **the host** when they describe what it does for a
+widget: the host draws the view, answers the services and keeps the user's
+data.
+
+## Where to start
+
+1. Follow the [creator guide](guide.md): from `overcrow-widget init` to a
+   submitted widget, in twelve short steps.
+2. Read the [reference widgets](widgets.md): the built-ins, with their tests.
+3. Go deeper, one topic per page: the [manifest](manifest.md), the
+   [view](view.md), the [style](style.md), the [logic](logic.md),
+   [services and permissions](services.md), [forms](forms.md).
+4. Use the tools: the [CLI](cli.md), [tests](testing.md) and the
+   [development channel](dev-channel.md) that runs your widget in OverCrow
+   while you write it.
+5. Look up an element, a style property, a service or an SDK function in the
+   [reference](reference.md).
+6. Before you publish, read [the package](package.md),
+   [security](security.md) and [publishing and review](publishing.md).
+
+Widgets run on Windows and Linux alike: the same package, the same SDK and
+the same rendering.