Decision Blocks

Decision Blocks is an Obsidian plugin for same-file, quote-anchored decision tracking. It keeps the decision question, choices, state, timestamps, and audit thread in the same Markdown note as the prose the decision refers to.

Why it exists

• Keep decision state beside the source text instead of in frontmatter, sidecar files, or plugin storage.
• Anchor each decision to an exact quote so context survives refactors better than loose note-level metadata.
• Preserve a machine-readable format that works for humans, scripts, and LLM-assisted workflows.

Same-file fenced format

Every note stores decision data in exactly one fenced JSON block named decision-blocks.

```decision-blocks
{
  "schemaVersion": 1,
  "items": [
    {
      "id": "dec_lm4q3...",
      "anchor": {
        "exact": "Launch in September",
        "prefix": "The current proposal is to ",
        "suffix": " if approvals land in time.",
        "pos": 128
      },
      "createdAt": "2026-07-18T12:00:00.000Z",
      "createdBy": "human",
      "question": "Should we commit to the September launch window?",
      "mode": "single",
      "choices": [
        { "id": "ch_a", "label": "Commit now", "detail": "Accept the current plan." },
        { "id": "ch_b", "label": "Delay", "detail": "Push to the next release train." }
      ],
      "state": {
        "status": "open",
        "selectedChoiceIds": [],
        "deferUntil": null,
        "decidedAt": null,
        "decidedBy": null,
        "updatedAt": "2026-07-18T12:00:00.000Z",
        "updatedBy": "human",
        "choiceSnapshots": []
      },
      "thread": []
    }
  ]
}
```

The plugin refuses destructive repairs. If the fence JSON or schema is invalid, writes fail and the note stays unchanged.

Workflow

1. Select prose in a Markdown note.
2. Run Add decision from selection.
3. Enter the decision question and one or more choices.
4. Review and update the decision from the sidebar or the Reading View pill.

single mode stores one selected choice. multiple mode stores a set. Reading View renders one summary pill in place of the raw fence, while Live Preview hides the fence and keeps quote highlights in the editor.

Tandem coexistence

• If a note ends with a trailing tandem-comments fence, decision-blocks is written immediately before it.
• Tandem stays at EOF.
• Unrelated bytes, including line endings, are preserved.

Privacy and data handling

• No network requests.
• No telemetry.
• No ads.
• No external services.
• Decision content is stored only in the note that owns the decision-blocks fence.
• The only plugin setting is local actorName, which is a device-local preference for default authorship text.
• Actual actor values written to decision records and thread entries are stored in the Markdown note, not in plugin storage.

Compatibility

The manifest sets "isDesktopOnly": false, and the implementation uses mobile-compatible Obsidian APIs. Automated compatibility coverage runs in the test suite and build pipeline, but mobile support still needs real-device validation before calling it production-ready.

Installation

Once the plugin is approved for the Obsidian Community Plugins directory, install it from Settings -> Community plugins -> Browse and search for Decision Blocks.

Until then, use one of these options:

BRAT

1. Install the BRAT plugin in Obsidian.
2. Add the beta plugin from https://github.com/orsk-moscow/decision-blocks.
3. Enable Decision Blocks after BRAT installs the build artifacts.

Manual

1. Download manifest.json, main.js, and styles.css from the latest GitHub release.
2. Copy them into <your-vault>/.obsidian/plugins/decision-blocks/.
3. Reload Obsidian and enable Decision Blocks.

For mobile, confirm your sync flow copies all three files before enabling the plugin on-device.

Local development

Symlink the repository root into your vault so Obsidian loads the plugin directly from the working tree:

ln -s /absolute/path/to/decision-blocks /absolute/path/to/vault/.obsidian/plugins/decision-blocks

Builds emit main.js at the repository root, which keeps the symlink workflow simple for desktop and mobile test vaults.

Run the standard checks:

npm ci
npm run lint
npm run typecheck
npm test
npm run build
npm run package

Release process

1. Run npm version <x.y.z>.
2. The version lifecycle script syncs manifest.json and versions.json to the package version.
3. Push the matching GitHub tag in plain semver form such as 0.1.1.
4. GitHub Actions validates that the tag, package.json, and manifest.json all match, then drafts a release with main.js, manifest.json, and styles.css.

Next step

After release automation is in place and mobile behavior is validated on real devices, the next milestone is submitting the plugin to the Obsidian Community Plugins directory. This repository is not claiming directory inclusion yet.