# PARA Review

An Obsidian community plugin with independent Inbox and expired-note review workflows.

## Status

Release `0.6.0` adds commands to archive and return whole Projects with movement history, and uses folder-aware archival for tagged main Projects in expired-note review. The owner authorized release while the focused disposable-vault UI check remains open. Submission to the Obsidian Community Directory is pending owner authentication.

## Scope

The plugin provides two user-started review workflows shared with `nvim-obsidian-para-flow`:

- open the oldest Inbox note first;
- edit the note in Obsidian's native Markdown editor;
- sort it into a configured PARA folder while adding only missing required metadata;
- skip a note for the current pass, pause review, or move it to the configured Obsidian trash after confirmation;
- set the current Inbox note's `expired_at` through the shared calendar without advancing the queue;
- preflight all required input and destination conflicts before mutation;
- stop with an exact recovery report if a multi-step mutation cannot be fully rolled back;
- review Projects whose `deadline` has passed and other non-archive Markdown notes that opt in with `expired_at`; strict `YYYY-MM-DD` and `DD.MM.YYYY` calendar dates are accepted, while rescheduling writes ISO;
- reschedule a candidate through a native today-or-later calendar or explicit strict manual entry, archive it, confirm trash, or skip it without background mutation;
- require a configurable new project status before an expired Project is archived.
- archive a selected Project and its folder, and return an archived Project to work with a required reason and a movement history in the main note.

Capture, Home, general search, multi-note merge, and Daily notes remain outside this plugin.

## Implemented foundation

- direct-child Markdown filtering for the configured Inbox folder;
- FIFO ordering by creation time with a deterministic path tie-breaker;
- immutable source snapshots for later external-change preflight;
- independent active, finished, paused, closed, and halted session states;
- immutable complete, skip, pause, close, and halt transitions;
- summaries that distinguish an empty Inbox from a pass completed with skipped notes.
- a pure PARA metadata planner that preserves existing values, reports missing input, moves last, and emits reverse compensation steps.
- an async transaction executor that rechecks file and metadata snapshots, blocks destination conflicts, applies properties in order, moves last, and reports complete or incomplete rollback.
- an Obsidian mutation adapter that performs typed Markdown lookup, reads fresh frontmatter snapshots, uses atomic frontmatter edits, moves through `FileManager.renameFile()`, and sends confirmed deletions through `FileManager.trashFile()`.
- a shared native `list-checks` icon for the ribbon action and review view, a native editor for the current FIFO note, and an `ItemView` with queue status and review controls.
- Projects, Areas, Resources, and Archives controls in an evenly spaced category row, with set-expiration, skip, pause, trash, and close grouped in a separate review-control row that wraps safely on narrow sidebars.
- Nested destination-folder selection, existing `#area` note selection when required, archive-reason input, transaction results, and exact halted recovery output.
- Resources can optionally link to a main project note: after any required Area selection, choose a project from the configured Projects root or `Без проекта` (No project). The plugin writes a full-path wikilink in `project` only when that property is empty. Closing the selector cancels the action.
- confirmed movement to the user's configured Obsidian trash only after a second source snapshot matches the pre-confirmation baseline; permanent deletion is not exposed.
- pause returns to the native editor, while close offers save, discard, and safe cancel when the current editor has unsaved changes.
- plugin-scoped modal action rows with theme spacing, wrapping, and native Obsidian buttons.
- ten Inbox-review commands that users can bind in Settings → Hotkeys; action commands are disabled unless an idle active item exists, the plugin defines no default hotkeys, and the review controls keep the assignment location visible.
- an independent expired-note queue, `archive-restore` ribbon/view, six current-item/session commands plus its opening command, a native calendar-first reschedule modal with manual dual-format fallback, visible invalid-metadata diagnostics, and Archives exclusion.

## Commands

- `Open inbox review` rebuilds the FIFO queue, opens the oldest note in Obsidian's native Markdown editor, and reveals the review view.
- `Sort current note into Projects`
- `Sort current note into Areas`
- `Sort current note into Resources`
- `Sort current note into Archives`
- `Set current note expiration date` writes canonical ISO `expired_at` and keeps the item current.
- `Skip current note`
- `Pause inbox review`
- `Move current note to trash`
- `Close inbox review`

Expired-note commands:

- `Open expired-note review`
- `Change current expiration date`
- `Archive current expired note`
- `Move current expired note to trash`
- `Skip current expired note`
- `Pause expired-note review`
- `Close expired-note review`

Project movement commands, available without starting a review:

- `Archive project` selects a tagged main project note, requires a new configured archive status and a reason, then moves its project folder (or root-level note) to `<Archives>/Projects`.
- `Return project to work` selects a project under `<Archives>/Projects`, requires a work status and return reason, offers a new or cleared `deadline`, then moves it back to the configured Projects root. An expired or invalid old deadline must be replaced or cleared.

Both commands confirm the exact source and destination before mutation. The main note receives a `История движения проекта` section with a dated status and reason entry for each move. On return, current `archived` and `archive_reason` properties are cleared; the history preserves their meaning. When archiving a tagged main Project from expired-note review, `Archive current expired note` runs the same folder-aware flow. Other expired notes keep the existing note-level archive action. A past `deadline` only offers the project for review; it never moves the project without an explicit action.
Queued notes within an archived project folder are removed from the current expired-note pass after the folder moves.

Assign commands in Obsidian's Settings → Hotkeys. Opening and project movement commands are always available; current-item commands require an idle item in their own session. No command has a default hotkey.

Before a PARA action, the plugin saves the current native Markdown view, reads a fresh source snapshot, collects every required input, and then revalidates the source immediately before the first mutation. Trash follows the same safety shape: save, inspect, confirm, inspect again, and delete only if both inspections match. Canceling a selector or prompt leaves the note and session unchanged.

The project list includes `#projects` Markdown notes in the configured Projects root and notes directly inside a project folder whose filename matches that folder, optionally prefixed with `00. `. Project documentation is excluded even if tagged `#projects`. The canonical `Templates/Projects.md` displays linked notes from `3. Resources` with Dataview. Existing Resources are not backfilled.

Inbox expiration uses the same calendar-first modal and strict manual fallback as expired-note
rescheduling. It accepts today or later, saves and revalidates the active source, and writes through
`FileManager.processFrontMatter()`. Cancel, invalid input, and source changes perform no mutation or
queue transition.

## Settings

The plugin stores explicit vault-relative roots for Inbox, Projects, Areas, Resources, and Archives. Projects and Areas also have explicit index wikilinks used only when a sorted note is missing its `links` property. `Project archive statuses` is a comma-separated non-empty list with defaults `Завершено, Отменено`. Settings are persisted through Obsidian's plugin data API; paths and archive destinations are not guessed.

## Development

Requirements: Node.js 18 or newer and npm.

```sh
npm install
npm run check
npm run dev
```

Develop and manually test only in a disposable Obsidian vault. A production build writes `main.js` at the repository root; the file is ignored by Git and is intended for release assets.

## Documentation

Product design, roadmap, decisions, and manual evidence are maintained in Russian in the canonical Obsidian project:

- `1. Projects/obsidian para flow/Плагин для PARA Обсидиан.md`
- `1. Projects/obsidian para flow/DESKTOP_INBOX_REVIEW.md`
- `1. Projects/obsidian para flow/ARCHIVE_REVIEW_DESIGN.md`

This repository contains only code-adjacent English contracts needed to develop, verify, and release the plugin.

## Privacy

The plugin is local-only. It does not transmit vault content, filenames, metadata, or usage information and includes no telemetry.