From 78b6bed570b61ae3b466ef38ece1e81ef4f08d8e Mon Sep 17 00:00:00 2001 From: Review Bot Date: Fri, 17 Apr 2026 03:10:27 -0700 Subject: [PATCH] docs: backfill notes docs Nightshift-Task: docs-backfill Nightshift-Ref: https://github.com/marcus/nightshift --- README.md | 30 +++++++- website/docs/command-reference.md | 16 ++++ website/docs/notes.md | 119 ++++++++++++++++++++++++++++++ website/sidebars.js | 1 + 4 files changed, 165 insertions(+), 1 deletion(-) create mode 100644 website/docs/notes.md diff --git a/README.md b/README.md index db67f9f2..eb3f9cff 100644 --- a/README.md +++ b/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 ` | | Show issue tree | `td tree ` | +### Notes + +| Action | Command | +| ------------------- | ---------------------------------------- | +| Create note | `td note add "Architecture decisions"` | +| List notes | `td note list --search "oauth"` | +| Show note | `td note show ` | +| Edit note | `td note edit --title "ADR"` | +| Pin or archive note | `td note pin ` / `td note archive ` | + ### 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) diff --git a/website/docs/command-reference.md b/website/docs/command-reference.md index 7260e3e2..a1b8e793 100644 --- a/website/docs/command-reference.md +++ b/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 [--json]` | Display full note details | +| `td note edit [flags]` | Update note. Flags: `--title`, `--content`. With no flags, opens the current content in your editor | +| `td note delete ` | Soft-delete note | +| `td note pin ` | Pin note | +| `td note unpin ` | Unpin note | +| `td note archive ` | Archive note | +| `td note unarchive ` | Unarchive note | + +`td note list` hides archived notes by default, orders pinned notes first, and defaults to 50 results. + ## Query & Search | Command | Description | diff --git a/website/docs/notes.md b/website/docs/notes.md new file mode 100644 index 00000000..d536bcbb --- /dev/null +++ b/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 [--json]` | Show one note | +| `td note edit [--title ...] [--content ...]` | Update a note | +| `td note delete ` | Soft-delete a note | +| `td note pin ` / `td note unpin ` | Pin or unpin a note | +| `td note archive ` / `td note unarchive ` | Archive or restore a note to the default list | diff --git a/website/sidebars.js b/website/sidebars.js index 4da1f856..d2594569 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -9,6 +9,7 @@ const sidebars = { 'boards', 'dependencies', 'query-language', + 'notes', 'epics', 'work-sessions', 'deferral',