mirror of
https://github.com/narrrl/narl-workspace.git
synced 2026-11-04 00:47:01 +01:00
docs: a guide, a wiki and screenshots
The README grew a section per feature and is a good reference, but nothing said where to begin. docs/wiki now has a getting-started page, a guide that walks through one day with the workspace and explains each part where it comes up, and a page per part of the app, each with screenshots of what it describes. Three pages are read out of the code rather than written, so they cannot drift from it: the keys and commands from Help.svelte and commands.ts, the same lists `:help` draws; the settings from .env.example, which gains a heading for the vault, trash and history settings so they no longer sit under mail; and the API from the README's table. `make wiki` writes them, and `--check` fails when one is stale or a link between pages leads nowhere. `--publish` lays the pages out for a GitHub wiki: links without `.md`, images beside them, `[[` escaped so the wiki does not take a command's help text for a link to a page. The screenshots are taken by `make screenshots`: the debug binary on a temporary data directory, with a password made up for the run, filled with an example workspace over the API, and a headless Chromium driven over the DevTools protocol through the views the docs show. Nothing outside the temporary directory is touched but docs/images, and the pictures are cut to 256 colours, a third of their size, which a dark UI does not show. The README opens with the banner, a CI badge, the guide, the features grouped by what they are for, and six of the screenshots.
This commit is contained in:
1 parent
7b2fd5579c
commit
4eb663e2d7
41 files changed
+2523
-25
No files matched your search
@@ -0,0 +1,56 @@
|
||||
# Capture
|
||||
|
||||
A thought arrives when no tab is open. `POST /api/capture` writes it down from
|
||||
anything that can send a request: a phone shortcut, a script, `curl`. It takes a
|
||||
token in place of a login.
|
||||
|
||||
## Tokens
|
||||
|
||||
```text
|
||||
:token add phone makes one, shows it once and copies it
|
||||
:token lists them, with when each was last used
|
||||
:token rm phone and that one captures nothing from the next request on
|
||||
```
|
||||
|
||||
A token opens this one route and nothing else. It cannot read anything, not even
|
||||
the list of spaces. Only its SHA-256 is kept on the server, so it is shown once,
|
||||
when it is made. Wrong tokens slow down the way wrong passwords do, on a line of
|
||||
their own, so guessing at them does not hold up the login.
|
||||
|
||||
## Sending
|
||||
|
||||
```sh
|
||||
curl -H "Authorization: Bearer nwc_…" -H 'content-type: application/json' \
|
||||
-d '{"text":"call the bank"}' https://your-host/api/capture
|
||||
```
|
||||
|
||||
| field | meaning |
|
||||
| --- | --- |
|
||||
| `text` | what to write down; for a card, the first line is the title and the rest its notes |
|
||||
| `to` | `"card"` (the default) or `"diary"` |
|
||||
| `space` | for a card, the slug of the space whose inbox it goes in |
|
||||
|
||||
- `"to": "card"` puts a card in the inbox of the space named by `space`, or else
|
||||
of the first space that has a board.
|
||||
- `"to": "diary"` adds `- 14:05 call the bank` to the end of today's entry, in
|
||||
`WORKSPACE_TIMEZONE`, and starts the entry from `templates/day` when there is
|
||||
none yet.
|
||||
|
||||
The answer says where it went: `{"to":"card","id":7,"where":"work/backlog"}`.
|
||||
|
||||
## From a phone
|
||||
|
||||
**iPhone**: in Shortcuts, make a shortcut with *Ask for Input*, then *Get
|
||||
Contents of URL*:
|
||||
|
||||
- URL: `https://your-host/api/capture`
|
||||
- Method: `POST`
|
||||
- Headers: `Authorization` = `Bearer nwc_…`
|
||||
- Request body: JSON, with `text` set to the *Provided Input*, and `to` set to
|
||||
`diary` if that is where it should go.
|
||||
|
||||
**Android**: in [HTTP Shortcuts](https://http-shortcuts.rmy.ch/), make a shortcut
|
||||
with a text-input variable, method `POST`, the same header, and a JSON body
|
||||
`{"text": "{{input}}"}`.
|
||||
|
||||
Either one can sit on the home screen, or behind the share sheet.
|
||||
Reference in new issue
Block a user