From b2d6603dcf774491f0966e809bffe49250bffe17 Mon Sep 17 00:00:00 2001 From: Tyler Koenig Date: Fri, 15 May 2026 22:01:47 -0400 Subject: [PATCH] docs: add README and MIT license --- LICENSE | 21 ++++++++ README.md | 156 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 177 insertions(+) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..42fa632 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Tyler Koenig + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..0380ff8 --- /dev/null +++ b/README.md @@ -0,0 +1,156 @@ +# nib + +Capture-first note system. Catch thoughts, todos, and events before they slip — from terminal or browser. Everything lives in a single SQLite file. + +nib uses a tiny grammar to extract structure from plain text. You type naturally, and nib figures out what it is: a thought, a todo with a due date, an event, a titled reference. Tags, descriptions, and time anchors are pulled out automatically. The body stays as markdown. + +When something proves useful, promote it to a card (snippet, template, checklist, decision, link) for quick reuse. Cards track usage and float to the top. + +## Install + +Requires Go 1.24+. + +``` +go build -o nib . +``` + +Data lives at `~/.nib/nib.db` by default. Override with `NIB_DB=/path/to/file.db`. + +## Quick start + +```bash +# capture a thought +nib "proxy_pass needs a trailing slash" + +# todo +nib "- buy mass gainer @tomorrow #errands" + +# titled entry with description +nib "|nginx proxy trick // always forget this #ops" + +# todo with a title +nib "- |deploy staging // rebuild docker image #ops" + +# list recent entries +nib ls + +# list by tag +nib ls --tag ops + +# list a specific month +nib ls --month 2026-05 + +# start the web UI +nib serve +``` + +Open `http://localhost:4444` for the browser interface. + +## Grammar + +The full grammar fits on an index card. Here's what matters: + +### Kind prefixes + +The first character decides what kind of entry you're creating. + +| Input | Kind | Example | +|-------|------|---------| +| bare text | thought | `just an idea` | +| `- text` | todo | `- buy milk @tomorrow` | +| `@time text` | event | `@friday 2pm lunch with alex` | +| `!time text` | reminder | `!3pm call dentist` | + +The dash needs a space after it. `-deploy` is a thought, `- deploy` is a todo. + +### Titles and descriptions + +Give an entry a name with `|` at the start. Add a description with `//`. + +``` +|nginx proxy trick +proxy_pass http://backend/; + +|deploy checklist // for staging #ops +1. docker build +2. docker push +3. ssh prod && restart + +// quick reference for proxy config +the actual body text goes here + +body text // this part becomes the description +``` + +Title shows as the scan label in list view. Description appears in the detail pane. Both are optional — most captures won't need them. + +### Tags and flags + +Tags and flags work anywhere in the input. They're extracted and removed from the body. + +``` +deploy nginx #ops #infra → tags: ops, infra +important thing !pin → pinned to top +use ##channel in slack → literal #channel in body (escaped) +``` + +### Cards + +Promote a fluid entry to a card for reuse: + +```bash +nib promote snippet # code trick, copy-to-clipboard +nib promote template # has ${slots} to fill +nib promote checklist # step-through items +nib promote decision # chose/why/rejected +nib promote link # URL with an open button +``` + +Or use `^type` inline: `nib "proxy trick #nginx ^card"` + +## CLI commands + +| Command | What it does | +|---------|-------------| +| `nib ` | Capture (shorthand for `nib add`) | +| `nib ls` | List entries — filter with `--tag`, `--date`, `--month`, `--from`/`--to` | +| `nib cards` | List cards sorted by usage | +| `nib edit ` | Open in `$EDITOR` | +| `nib copy ` | Copy body to clipboard | +| `nib promote [type]` | Promote to card | +| `nib demote ` | Strip card, back to fluid | +| `nib absorb ` | Merge source into target | +| `nib delete ` | Soft delete (repeat to hard delete) | +| `nib serve` | Start web UI on `:4444` (or `--port`) | + +IDs are prefix-matchable. If `01KRQ4` is unique, that's enough. + +## Web UI + +`nib serve` starts a local web interface with: + +- **Capture bar** — same grammar as the CLI +- **Stream view** — entries grouped by date, newest first +- **Cards view** — promoted cards sorted by use count +- **Tag rail** — filter by tag +- **Month navigator** — browse by date range +- **Detail pane** — full entry view, double-click to edit +- **Keyboard shortcuts** — `j`/`k` navigate, `n` to capture, `p` to promote, `e` to edit, `dd` to delete + +Dark and light themes. Toggle with the button in the header. + +## Data + +Everything is one SQLite file. Back it up, sync it, move it between machines — it's just a file. WAL mode is on for concurrent reads. + +```bash +# back up +cp ~/.nib/nib.db ~/.nib/nib.db.bak + +# use a different database +NIB_DB=/path/to/other.db nib ls +``` + +## License + +MIT