Metadata-Version: 2.4
Name: navig-notes
Version: 0.2.0
Summary: navig notes -- your web sticky notes on this computer: the NAVIG Dock syncs every note you keep on a page, a site or everywhere, so you can list, search, add and export them from the command line, and NAVIG's Recall can find them (never sent to an AI unless you allow it).
Author: navig
License: MIT
Project-URL: Homepage, https://navig.run
Project-URL: Documentation, https://navig.run/docs
Keywords: navig,cli,plugin,notes,sticky-notes,web,annotations,search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: navig-sdk>=2.10.0
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.7.0
Dynamic: license-file

# navig-notes

<!-- navig:plugin-card:start -->
<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->

> Your web sticky notes on this computer: the NAVIG Dock syncs every note you keep on a page, a site or everywhere, so you can list, search, add and export them from the command line, and NAVIG's Recall can find them (never sent to an AI unless you allow it).

**Works on its own** — its own CLI, no navig required · v0.2.0 · not on PyPI yet (install from source below)

**On its own** (no navig needed)

```bash
pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-notes"
navig-notes --help   # no navig needed
```

**With navig**

```bash
pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-notes"
navig notes --help
```

<details><summary>Commands</summary>

| Command | What it does |
|---|---|
| `navig notes add` | Add a note — it appears in the browser on the Dock's next sync. |
| `navig notes export` | Export notes to a file the Dock's Library can import (JSON) or anyone can read (Markdown). |
| `navig notes list` | Your notes, most recently edited first. |
| `navig notes rm` | Delete a note everywhere (the Dock moves it to its Trash on the next sync). |
| `navig notes search` | Search every note's title, text, tags, page title and website. |
| `navig notes share pull` | Read the Space's .navig/notes/*.md back — ids kept, newer revision wins. |
| `navig notes share push` | Write every note into the Space's .navig/notes/ as .md files (ids preserved). |
| `navig notes share status` | How many notes, how many files, and which side is ahead. |
| `navig notes show` | One note in full. |
| `navig notes status` | How many notes, where they live, and when the Dock last synced. |

</details>

<!-- navig:plugin-card:end -->

Your web sticky notes on this computer. The **NAVIG Dock** keeps notes on web pages — on one
page, a whole site, or everywhere — in the browser; with NAVIG running it syncs them here, to
`<navig data dir>/notes.db`. Nothing is uploaded.

```bash
navig notes list                      # most recently edited first (--site github.com, --tag work)
navig notes search retry path          # every word must match; "quote a phrase"
navig notes show 3f2a                  # one note in full (an id prefix is enough)
navig notes add "call the bank"        # an Everywhere note — it appears in the browser on the next sync
navig notes add "check CI" --url https://github.com/org/repo/issues/12   # a note on that page
navig notes rm 3f2a                    # deleted everywhere (the Dock moves it to its Trash)
navig notes export notes.json          # re-importable in the Dock's Notes Library (or .md)
navig notes status                     # counts, the store, the last Dock sync
navig notes share push --space <n>     # every note → <space>/.navig/notes/*.md (ids kept)
navig notes share pull --space <n>     # back again — newer revision wins, same rule as the sync
navig notes share status --space <n>   # which side is ahead; orphan files are never deleted
```

## Sharing notes with a Space

A Space folder is how a team shares things, so shared notes are plain files in
`<space>/.navig/notes/<id>.md`: frontmatter carries the id, revision, scope, geometry, tags
and sharing level; the body travels byte for-byte. Push writes atomically and skips
unchanged files; pull merges with the store's own revision rule (the same last-writer-wins
the Dock sync uses); `--space` takes a Space name or a path and defaults to the active Space,
else the nearest `.navig` above you — never the global config dir. Reminders are personal and
stay local; a pulled note shows up in the Dock as *from NAVIG*.

## How the sync works

Every note carries a revision that each writer bumps. The Dock pushes what changed since its
last push (edits, and deletions as tombstones) to `POST /api/deck/notes/sync` and gets back
what changed here since its cursor. **The higher revision wins**; an older copy never
overwrites a newer one, and the side that sent the older copy is handed the newer one. The
Dock syncs a few seconds after any change, every 5 minutes, and when Chrome starts; when NAVIG
is not running the notes simply stay in the browser.

The routes answer only this computer (`is_local_request`) and sit behind the `notes` module.

## Recall and the agent

The Dock's Notes Library → Settings → **NAVIG on this computer**:

| Setting | What happens |
|---|---|
| Keep a copy in NAVIG (default) | Synced here; `navig notes` and `navig recall` find them. Never sent to an AI. |
| Copy + the agent may use them | The same, and agent context may include them — that text goes to the AI provider you chose. |
| Off | Nothing leaves the browser. |

`navig recall ingest --source notes` reads synced notes: your words as yours, lines you quoted
from a page (`> …`) as page captures, and checkboxes (`- [ ]` / `- [x]`) as your open / done
tasks. A note deleted in the browser is forgotten at the next ingest.
