Annotate documentation omits per-file version history and privacy controls

[rNoz]

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!

[backnotprop]

Confirming this is a legitimate gap. There was a PR addressing it (#1087 by @rNoz) and the writeup was accurate. We closed it only because our docs moved to a new platform: the live site is now https://docs.plannotator.ai and the docs source lives in a separate private repo, so edits to this repo's docs content no longer ship.

The same points (annotate copies file contents into the data dir on open, where the copies live, and the PLANNOTATOR_ANNOTATE_HISTORY / annotateHistory controls) are queued for the new docs. Note the behavior itself is also under review, we are weighing opt-in history with retention controls, so the docs will be written to match whatever lands. Keeping this issue open until the new docs page is live.

[rNoz]

Great, thanks - happy to help! When applied there, feel free to cross-link this issue and close it ;)