docs: backfill notes docs

README.md

@@ -8,7 +8,7 @@ A minimalist CLI for tracking tasks across AI coding sessions. When your context
 
 `td` is a lightweight CLI for tracking tasks across AI coding sessions. It provides structured handoffs (done/remaining/decisions/uncertain) so new sessions continue from accurate state instead of guessing. Session-based review workflows prevent "works on my context" bugs. Works with Claude Code, Cursor, Copilot, and any AI that runs shell commands.
 
-**Key Features**: Query-based boards, dependency graphs, epic tracking, powerful query language (TDQ), session analytics, and state machine workflows.
+**Key Features**: Query-based boards, freeform project notes, dependency graphs, epic tracking, powerful query language (TDQ), session analytics, and state machine workflows.
 
 ![td](docs/td.png)
 
@@ -24,6 +24,7 @@ A minimalist CLI for tracking tasks across AI coding sessions. When your context
 - [Epics](#epics)
 - [Multi-Issue Work Sessions](#multi-issue-work-sessions)
 - [File Tracking](#file-tracking)
+- [Notes](#notes)
 - [Minor Tasks](#minor-tasks)
 - [Analytics & Stats](#analytics--stats)
 - [Full Command Reference](#full-command-reference)
@@ -364,6 +365,22 @@ td files td-a1b2                    # Shows [modified], [unchanged], [new], [del
 
 Files are SHA-tracked at link time. No more "did I already change this file?"
 
+## Notes
+
+> Full documentation: [Notes](https://marcus.github.io/td/docs/notes)
+
+Use notes for project knowledge that should stay local and searchable without becoming an issue: architecture decisions, meeting notes, scratch plans, debugging breadcrumbs, or runbooks for future sessions.
+
+```bash
+td note add "Architecture decisions"
+td note list --search "oauth"
+td note show nt-abc123
+td note pin nt-abc123
+td note archive nt-abc123
+```
+
+If you omit `--content` on `td note add` or `td note edit`, `td` opens `$EDITOR` (falling back to `vi`) so you can write longer notes in your normal editor.
+
 ## Minor Tasks
 
 For trivial changes that don't need separate review sessions:
@@ -458,6 +475,16 @@ Analytics are stored locally and help identify workflow patterns. Disable with `
 | Add child to parent | `td tree add-child <parent> <child>` |
 | Show issue tree     | `td tree <id>`                       |
 
+### Notes
+
+| Action              | Command                                  |
+| ------------------- | ---------------------------------------- |
+| Create note         | `td note add "Architecture decisions"`   |
+| List notes          | `td note list --search "oauth"`          |
+| Show note           | `td note show <note-id>`                 |
+| Edit note           | `td note edit <note-id> --title "ADR"`   |
+| Pin or archive note | `td note pin <note-id>` / `td note archive <note-id>` |
+
 ### Query & Search
 
 | Action       | Command                 |
@@ -524,6 +551,7 @@ open --> in_progress --> in_review --> closed
 Full documentation is available at [marcus.github.io/td](https://marcus.github.io/td/), including:
 - [Getting Started](https://marcus.github.io/td/docs/intro)
 - [Core Workflow](https://marcus.github.io/td/docs/core-workflow)
+- [Notes](https://marcus.github.io/td/docs/notes)
 - [AI Agent Integration](https://marcus.github.io/td/docs/ai-integration)
 - [Command Reference](https://marcus.github.io/td/docs/command-reference)
 

website/docs/command-reference.md

@@ -62,6 +62,22 @@ td create "Document sync failure modes" \
 cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file -
 ```
 
+## Notes
+
+| Command | Description |
+|---------|-------------|
+| `td note add "title" [--content "..."]` | Create a note. Omitting `--content` opens `$EDITOR` (fallback: `vi`) |
+| `td note list [flags]` | List notes. Flags: `--pinned`, `--archived`, `--all`, `--search`, `--limit`, `--json`, `--output json` |
+| `td note show <id> [--json]` | Display full note details |
+| `td note edit <id> [flags]` | Update note. Flags: `--title`, `--content`. With no flags, opens the current content in your editor |
+| `td note delete <id>` | Soft-delete note |
+| `td note pin <id>` | Pin note |
+| `td note unpin <id>` | Unpin note |
+| `td note archive <id>` | Archive note |
+| `td note unarchive <id>` | Unarchive note |
+
+`td note list` hides archived notes by default, orders pinned notes first, and defaults to 50 results.
+
 ## Query & Search
 
 | Command | Description |

website/docs/notes.md

@@ -0,0 +1,119 @@
+---
+sidebar_position: 7
+---
+
+# Notes
+
+Use notes for information that should stay close to the project but does not belong in the issue lifecycle: architecture decisions, meeting notes, rough plans, runbooks, or research scraps you want future sessions to find quickly.
+
+Unlike issues, notes do not move through statuses or review. They are just local, searchable documents stored in the same project data as the rest of `td`.
+
+## Creating Notes
+
+Create a note with a title and inline content:
+
+```bash
+td note add "Architecture decisions" --content "Use OAuth device flow for local development."
+```
+
+If you omit `--content`, `td` opens your default editor so you can write longer content comfortably:
+
+```bash
+td note add "Release checklist"
+```
+
+`td` uses `$EDITOR` when it is set, and falls back to `vi` otherwise.
+
+## Listing and Searching
+
+`td note list` shows unarchived notes by default. Results are ordered with pinned notes first, then by most recently updated note.
+
+```bash
+td note list
+td note list --search "oauth"
+td note list --pinned
+td note list --archived
+td note list --all
+```
+
+Use `--limit` to cap the number of results:
+
+```bash
+td note list --limit 10
+```
+
+For scripts and tooling, use JSON output:
+
+```bash
+td note list --json
+td note list --output json
+```
+
+## Viewing a Note
+
+Show the full contents of a single note:
+
+```bash
+td note show nt-abc123
+```
+
+Use JSON when you need structured output:
+
+```bash
+td note show nt-abc123 --json
+```
+
+## Editing Notes
+
+Update the title, the content, or both:
+
+```bash
+td note edit nt-abc123 --title "ADR: OAuth device flow"
+td note edit nt-abc123 --content "Updated implementation notes."
+```
+
+If you run `td note edit` with no flags, `td` opens the existing content in your editor and saves the edited result when the editor exits:
+
+```bash
+td note edit nt-abc123
+```
+
+## Pinning and Archiving
+
+Pin notes you want to keep at the top of `td note list`:
+
+```bash
+td note pin nt-abc123
+td note unpin nt-abc123
+```
+
+Archive notes when they should stay around but no longer appear in the default list:
+
+```bash
+td note archive nt-abc123
+td note unarchive nt-abc123
+```
+
+Archived notes still appear in `td note list --archived` and `td note list --all`.
+
+## Deleting Notes
+
+Delete a note when you no longer want it in normal note views:
+
+```bash
+td note delete nt-abc123
+```
+
+This is a soft delete, so the note is removed from regular `td note` lookups without immediately erasing the underlying record.
+
+## Command Summary
+
+| Command | What it does |
+|---------|---------------|
+| `td note add "title" [--content "..."]` | Create a note |
+| `td note list [flags]` | List notes with filters and search |
+| `td note show <id> [--json]` | Show one note |
+| `td note edit <id> [--title ...] [--content ...]` | Update a note |
+| `td note delete <id>` | Soft-delete a note |
+| `td note pin <id>` / `td note unpin <id>` | Pin or unpin a note |
+| `td note archive <id>` / `td note unarchive <id>` | Archive or restore a note to the default list |

website/sidebars.js

@@ -9,6 +9,7 @@ const sidebars = {
         'boards',
         'dependencies',
         'query-language',
+        'notes',
         'epics',
         'work-sessions',
         'deferral',