backnotprop / backnotprop/plannotator
Annotate documentation omits per-file version history and privacy controls
- Dominant language
- TypeScript
- Stars
- 8.7k
- Forks
- 649
- Avg merge
- 11h 12m
- Merged PRs (30d)
- 109
Description
## Summary
The public annotate command documentation explains supported files, URLs, folders, and review-gate behavior, but it does not explain the existing per-file version history for eligible local files, its retention, or how to disable it.
## Current documentation
The annotate page does not tell users that opening a non-empty local markdown, text, or HTML file saves a history copy before the UI opens. It also omits the storage and active configuration locations, deduplication behavior, file-path identity, raw HTML versus `--markdown` history content, Version Browser integration, retention, opt-out precedence, and the input modes excluded from this history.
## Shipped behavior
- Non-empty local single-file `.md`, `.mdx`, `.txt`, `.html`, and `.htm` sessions are eligible to save history on open.
- History is keyed by the resolved file path, so reopening the same path can show the previous/current diff and earlier versions in the Version Browser.
- Consecutive identical content is deduplicated.
- Raw HTML annotation stores the HTML source in history; using `--markdown` stores the converted markdown content instead.
- Copies are stored indefinitely under `~/.plannotator/history/` by default, or under `history/` inside `PLANNOTATOR_DATA_DIR`, until the user manually deletes them.
- The active config file is `~/.plannotator/config.json` by default or `config.json` inside `PLANNOTATOR_DATA_DIR` when that variable is set.
- Users can disable annotate history with `PLANNOTATOR_ANNOTATE_HISTORY=0` or `"annotateHistory": false` in the active config file. The environment variable takes precedence over config.
- URL annotation, folder browsing, and last-message annotation do not use per-file version history.
## Impact
Without this documentation, users can miss a useful iteration feature and may incorrectly assume local file annotation is stateless. The omission is especially relevant for users reviewing sensitive documents who need to understand what content is copied, where it is stored, how long it remains, and how to opt out.
## Proposed scope
Add a focused per-file version history section to `apps/marketing/src/content/docs/commands/annotate.md` and document the environment variable in `apps/marketing/src/content/docs/reference/environment-variables.md`. This is a documentation-only contribution describing behavior already present in Plannotator 0.24.1; it does not change runtime behavior or introduce new gate behavior.
## Evidence
- The implementation is defined by annotate history setup in `packages/server/annotate.ts`, history storage and deduplication in `packages/shared/storage.ts`, and configuration resolution in `packages/shared/config.ts`.
- The contribution was rebased onto `upstream/main` at `2594b374` (Plannotator 0.24.1).
- Focused validation on 2026-07-20 passed: `bun run build:marketing` generated 40 pages, `bun run typecheck` passed, and `git diff --check` passed.
- No live browser session was run because the contribution changes documentation only.
## Contribution
I have a documentation-only update ready to contribute. About to do the last checks and push the PR => Done!
Contributor guide
Research direction
Read apps/marketing/src/content/docs/commands/annotate.md and apps/marketing/src/content/docs/reference/environment-variables.md, using packages/server/annotate.ts, packages/shared/storage.ts, and packages/shared/config.ts to verify the documented behavior. Add the per-file history, retention, storage, privacy controls, and excluded input modes, then run bun run build:marketing, bun run typecheck, and git diff --check.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100