ResearchPocket 2.2.2

ResearchPocket 2.2.2

ResearchPocket 2.2.2 fixes native restoration of a valid private library when
several cross-device updates arrive in reverse causal order. The hosted owner
app already restored this history correctly; the native CLI and TUI now reach
the same converged library.

Install

With Rust installed:

cargo install --locked --force research

Or download the verified archive for Linux, macOS, or Windows from the GitHub
release and check it against SHA256SUMS.

What changed

• Native deferred updates retry to a fixed point. A deferred update can
  depend on another deferred update that sorts after it. Native persistence now
  re-offers the set in bounded rounds until no additional predecessor can be
  satisfied instead of treating one unsuccessful pass as missing history.
• Interrupted restores repair themselves after upgrade. A failed native
  restore may already have recorded every immutable remote object. A later sync
  now retries those persisted deferred envelopes even when there is nothing to
  download, then continues with normal aggregate synchronization.
• Incomplete histories still fail closed. If a predecessor is genuinely
  absent after replay reaches a fixed point, synchronization stops before any
  local update is uploaded and keeps the same integrity error.

The fix was verified against a production-sized private repository that exposed
the failure and with a three-device contract test delivering a grandchild,
child, and predecessor in reverse order.

Upgrade an affected library

Revoke any credential that has been exposed in terminal output or shell history,
upgrade the native client, and run a normal synchronization cycle:

cargo install --locked --force research
research --version
research sync run

The expected version is research 2.2.2. Do not reconnect or delete the local
library after the earlier integrity error. The next sync reuses its durable
receipts and repairs the deferred projection without downloading or rewriting
the immutable history again.

This release does not change the synchronization protocol, SQLite schema,
operation-pack format, checkpoint format, aggregate generation, or repository
layout. Existing native and hosted clients remain wire-compatible.

GitHub release archives

Platform	Release asset
Linux GNU/glibc x86-64 (glibc 2.35 or newer)	research-v2.2.2-linux-amd64.tar.gz
Windows x86-64	research-v2.2.2-windows-amd64.zip
macOS Intel	research-v2.2.2-macos-amd64.tar.gz
macOS Apple Silicon	research-v2.2.2-macos-arm64.tar.gz

The archives remain unsigned. Verify the selected file with SHA256SUMS, or
build the exact tag with the pinned toolchain:

git clone --branch v2.2.2 --depth 1 \
  https://github.com/ResearchPocket/researchpocket.github.io.git
cd researchpocket.github.io
cargo build --locked --release

ResearchPocket 2.2.1

ResearchPocket 2.2.1

ResearchPocket 2.2.1 adds Research Zen: bounded authored documents — prose,
lists, and todos — that live beside your saves, synchronize between devices, and
can mention saved links inline. It also fixes a repository-growth bug that could
accumulate redundant snapshots in a private data repository indefinitely.

2.2.1 is the first release of this line. A v2.2.0 tag exists in the repository
but was never built or published.

Install

With Rust installed:

cargo install --locked --force research

Or download the verified archive for Linux, macOS, or Windows from the GitHub
release and check it against SHA256SUMS.

What changed

• Research Zen. A zen document is Markdown bounded to 256 KiB, stored as its
  own aggregate rather than inside the item library. Documents carry a title,
  tags, prose, GFM task lists, and research:item/<uuid> mentions that resolve
  against your local saves. Saved items remain URL-first and unchanged: a
  document is not a save without a link, it is a different thing.
• Todo counts are derived from the body, never stored. A checkbox toggled by
  clicking and one edited by hand are indistinguishable, and there is no counter
  that can fall out of step with the text.
• Concurrent edits merge at character level. A checkbox toggle is a text
  splice, so two devices flipping different boxes in the same list keep both
  changes, as do a toggle and a prose edit in the same paragraph.
• Zen documents synchronize. Both clients now carry the aggregate generation
  after their protocol-v1 phase. An operation whose causal predecessor has not
  arrived is deferred and retried rather than partially applied, and uploads are
  confirmed by reading the remote object rather than assumed from the write.
• research zen in the CLI: list, add, show, edit, delete, and
  restore. Bodies come from a file or standard input, because a document is
  prose and shells mangle prose. Listing reads projected metadata only; show
  is the one command that loads a body.
• The web workspace opens as a new-tab surface: the time, one input that
  both filters and creates, and the documents. Opening it costs nothing
  proportional to how much you have written, because no body is read to draw it.
• Checkpoint selection fix. A device that edited between building a
  checkpoint and confirming its upload never selected the checkpoint it had just
  published. Because tail thresholds are measured from the selected checkpoint,
  every later cycle minted and uploaded another full-library snapshot. Protocol
  v1 never prunes, so those accumulated permanently. Selection now requires only
  that this replica has already applied everything the checkpoint covers.
• A returning owner lands in their library. Opening the site with a library
  already on the device goes straight to the app instead of asking again how to
  create one. ?choose still reaches the chooser for adding or restoring a
  library.
• The web app no longer emits module preloads its own Content-Security-Policy
  forbids, which broke first load in strict browsers.

Upgrade an existing private library

Upgrade the native client, verify the version, and run one normal sync:

cargo install --locked --force research
research --version
research sync run

The expected version is research 2.2.1.

Zen documents are a new aggregate namespace under sync/v2/ops/zen/. They do
not touch protocol-v1 history, which remains immutable and is not pruned. A
2.1.x client that has not been upgraded will not see documents written by a
2.2.1 client; it continues to synchronize saves normally. Upgrade every device
you want documents on.

This release does not perform the item-aggregate migration. Saves continue to
synchronize over protocol v1.

GitHub release archives

Platform	Release asset
Linux GNU/glibc x86-64 (glibc 2.35 or newer)	research-v2.2.1-linux-amd64.tar.gz
Windows x86-64	research-v2.2.1-windows-amd64.zip
macOS Intel	research-v2.2.1-macos-amd64.tar.gz
macOS Apple Silicon	research-v2.2.1-macos-arm64.tar.gz

The archives remain unsigned. Verify the selected file with SHA256SUMS, or
build the exact tag with the pinned toolchain:

git clone --branch v2.2.1 --depth 1 \
  https://github.com/ResearchPocket/researchpocket.github.io.git
cd researchpocket.github.io
cargo build --locked --release

ResearchPocket 2.1.1

ResearchPocket 2.1.1

ResearchPocket 2.1.1 restores the explicit Firecrawl excerpt-replacement
contract and corrects enrichment reporting.

Install

With Rust installed:

cargo install --locked --force research

Or download the verified archive for Linux, macOS, or Windows from the GitHub
release and check it against SHA256SUMS.

What changed

• research enrich run <item-id> --provider firecrawl --replace-excerpt now
  replaces the excerpt with the fetched Markdown when the excerpt remains
  unchanged during the request.
• The same Firecrawl response remains available as the item's immutable,
  content-addressed captured document.
• Explicit replacement intent survives local leases and retries.
• An ordinary Firecrawl refresh still preserves the authored excerpt and now
  reports captured_document instead of incorrectly reporting excerpt.
• Concurrent excerpt edits continue to win: stale Firecrawl results update
  neither the excerpt nor its captured-document reference.

There is no domain-schema or synchronization-protocol change. A forward,
local-only SQLite migration records explicit replacement intent. Once a library
has been opened by 2.1.1, keep using 2.1.1 or newer with that local data
directory; older binaries do not recognize newer local migrations. The private
sync repository remains compatible.

Upgrade

Replace the 2.1.0 binary or run:

cargo install --locked --force research
research --version

The expected version is research 2.1.1. Existing libraries migrate
automatically on first open.

GitHub release archives

Platform	Release asset
Linux GNU/glibc x86-64 (glibc 2.35 or newer)	research-v2.1.1-linux-amd64.tar.gz
Windows x86-64	research-v2.1.1-windows-amd64.zip
macOS Intel	research-v2.1.1-macos-amd64.tar.gz
macOS Apple Silicon	research-v2.1.1-macos-arm64.tar.gz

The archives remain unsigned. Verify the selected file with SHA256SUMS, or
build the exact tag with the pinned toolchain:

git clone --branch v2.1.1 --depth 1 \
  https://github.com/ResearchPocket/researchpocket.github.io.git
cd researchpocket.github.io
cargo build --locked --release

ResearchPocket 2.1.0

ResearchPocket 2.1.0

ResearchPocket 2.1.0 keeps large private libraries responsive by bounding
browser restore work, moving shared-domain processing off the main thread, and
making routine projection writes proportional to the items that changed.

Install

With Rust installed:

cargo install --locked --force research

Or download the verified archive for Linux, macOS, or Windows from the GitHub
release and check it against SHA256SUMS.

What changed

• Native and browser synchronization now create and validate immutable
  protocol-v1 checkpoints after 100 newly covered batches or 2 MiB of decoded
  update payload. A pristine client restores the best checkpoint and applies
  only its uncovered tail.
• Browser checkpoint validation and remote application run in a dedicated
  worker and process direct operations in bounded chunks, keeping the page
  responsive while a large library is restored.
• Native installations keep one stable Loro peer identity. Causal frontiers now
  grow with active replicas instead of growing once per native edit.
• Local mutations and remote application return and persist only affected item
  projections after bootstrap instead of rewriting the complete item table.
• Enriched full-page Markdown is stored as an immutable SHA-256-addressed
  private object. List projections exclude its bytes, and the Reader downloads
  and validates it only when opened.
• The shared domain includes the validated item-aggregate, catalogue, migration
  barrier, and deterministic migration artifact primitives for the next sync
  generation. This release does not activate a protocol-v2 cutover or rewrite
  existing protocol-v1 history.

Upgrade and prime an existing private library

Upgrade the native client, verify the version, and run one normal sync:

cargo install --locked --force research
research --version
research sync run

The expected version is research 2.1.0. The first sync of an existing
repository may still replay its current protocol-v1 history once. It then
publishes the first checkpoint when the threshold is met. A fresh or reset
browser can use that checkpoint on its next connection instead of replaying the
covered history.

Protocol-v1 operation files remain immutable and are not pruned. ResearchPocket
2.0 clients ignore the optional checkpoint files, but upgrading every writer is
recommended before relying on the improved restore path.

GitHub release archives

Platform	Release asset
Linux GNU/glibc x86-64 (glibc 2.35 or newer)	research-v2.1.0-linux-amd64.tar.gz
Windows x86-64	research-v2.1.0-windows-amd64.zip
macOS Intel	research-v2.1.0-macos-amd64.tar.gz
macOS Apple Silicon	research-v2.1.0-macos-arm64.tar.gz

The archives remain unsigned. Verify the selected file with SHA256SUMS, or
build the exact tag with the pinned toolchain:

git clone --branch v2.1.0 --depth 1 \
  https://github.com/ResearchPocket/researchpocket.github.io.git
cd researchpocket.github.io
cargo build --locked --release

ResearchPocket 2.0.1

ResearchPocket 2.0.1

ResearchPocket 2.0.1 makes the stable CLI available through Cargo and turns the
public reference into a shorter, reader-focused guide.

Install

With Rust installed:

cargo install --locked research

Or download the verified archive for Linux, macOS, or Windows from the GitHub
release and check it against SHA256SUMS.

What changed

• The research, research-domain, and research-store crates now publish
  from one exact release tag in dependency order. Exact-version requirements
  ensure a Cargo installation uses the reviewed domain and store source from
  the same release.
• The public docs show only getting started, usage, migration, browser,
  data/sync/security, and current-release material.
• Internal engineering records, project material, and historical preview notes
  remain in the repository but no longer crowd the reader guide or its search
  results.
• Fenced code blocks have bundled language-aware highlighting and an accessible
  copy button with visible and announced feedback.

There is no domain, CRDT, synchronization protocol, SQLite, or machine-output
schema change in this patch.

Upgrade

Replace the 2.0.0 binary or run:

cargo install --locked --force research
research --version

The expected version is research 2.0.1. Existing 2.0.0 libraries and private
repositories require no migration.

GitHub release archives

Platform	Release asset
Linux GNU/glibc x86-64 (glibc 2.35 or newer)	research-v2.0.1-linux-amd64.tar.gz
Windows x86-64	research-v2.0.1-windows-amd64.zip
macOS Intel	research-v2.0.1-macos-amd64.tar.gz
macOS Apple Silicon	research-v2.0.1-macos-arm64.tar.gz

The archives remain unsigned. Verify the selected file with SHA256SUMS, or
build the exact tag with the pinned toolchain:

git clone --branch v2.0.1 --depth 1 \
  https://github.com/ResearchPocket/researchpocket.github.io.git
cd researchpocket.github.io
cargo build --locked --release

ResearchPocket 2.0.0

ResearchPocket 2.0 — your links, on your terms

ResearchPocket 2.0 is a local-first personal library for people who collect
useful URLs and want to keep ownership of the result.

Save first, even offline. Curate with your own titles, excerpts, notes, tags,
and favorites. Search from the CLI, TUI, or hosted owner application.
Synchronize across devices through immutable application updates, with GitHub
acting only as private transport—not as the judge of conflicting edits.

There is no required ResearchPocket account, no always-on application backend,
no silent URL deduplication, and no AI deciding how the library should be
organized. Authored data remains canonical, portable, and private by default.

Version 2.0 stabilizes the foundation tested through four preview releases.
Thank you to everyone who exercised capture, recovery, enrichment,
synchronization, hosted editing, and the many sharp edges between them.

Your research trail should belong to you.

What ships in 2.0

Local capture and curation

• Save absolute HTTP(S) URLs immediately without an account or network
  connection.
• Keep authored titles, excerpts, language, notes, tags, favorites, saved time,
  and duplicate URLs under explicit human control.
• Search URL, metadata, notes, and tags through the local SQLite FTS index.
• Delete and restore without erasing immutable history.
• Use stable human, JSON, or NDJSON command output, with diagnostics kept on
  stderr.
• Manage the same local library in a keyboard-first TUI, including add, edit,
  search, filters, enrichment, and private sync.

Browser capture and optional enrichment

• Install a per-user researchpocket://capture bridge on Linux, macOS, or
  Windows and save from the included Firefox bookmarklet.
• Capture bounded URL, title, description, language, and prompted tags from the
  already-loaded page without accepting credentials, repository coordinates,
  provider choices, database paths, or shell fragments.
• Save locally before any optional network work.
• Fill missing metadata through a bounded direct fetch or explicit Firecrawl
  configuration. Durable jobs retry safely and exact revision preconditions
  keep human edits, clears, and explicit empty values canonical.
• Retain bounded Firecrawl Markdown in the existing excerpt register for
  offline reading without turning ResearchPocket into a general webpage
  archive.

Private, convergent synchronization

• Synchronize a library through a private GitHub repository using immutable,
  uniquely addressed CRDT update envelopes.
• Preserve concurrent note edits at character granularity and apply
  deterministic causal rules for scalar fields, tags, lifecycle, and
  visibility.
• Batch multi-edit flushes into bounded, content-addressed operation packs
  without making Git commits or history part of conflict resolution.
• Keep queued updates through timeouts, rate limits, expired credentials,
  process interruption, duplicate delivery, and branch-head races.
• Detect changed bytes at an existing immutable path as an integrity error
  instead of overwriting data.

Offline-capable hosted owner application

• Create, search, edit, favorite, tag, delete, restore, and undo browser changes
  through the GitHub Pages owner application.
• Persist local browser state and the synchronization outbox in IndexedDB
  before network activity.
• Keep the fine-grained GitHub PAT in memory by default, with explicit
  session-only storage available; it never enters localStorage, IndexedDB,
  URLs, generated output, analytics, or service-worker caches.
• Continue editing offline and retry immutable uploads after connectivity or
  credentials return.
• Use responsive mobile controls, reader scrolling, customizable owner themes,
  and the first-party reference guide without third-party runtime scripts.

Upgrade from a preview

There is no new SQLite, domain, CRDT, or synchronization protocol migration
between v2.0.0-preview.4 and v2.0.0. The stable version retains domain schema
2, sync protocol 1, and the operation-packs-v1 transport feature.

Before replacing a preview binary:

1. Close every ResearchPocket CLI, TUI, browser-capture process, and owner-app
   tab.
2. Make an offline filesystem backup of each native local data directory.
3. Replace the binary and confirm research --version reports 2.0.0.
4. On macOS, reinstall the capture association because the per-user bridge
   contains its own binary copy.
5. Reload the hosted application, then run one sync from each upgraded device.

research --version
research capture install
research capture status
research status
research sync run

Clients older than preview 4 do not understand operation packs and
intentionally fail closed when they encounter one. Upgrade every native and
browser client for a private library before resuming synchronization. Do not
delete operation files, edit packs, squash repository history, or downgrade a
migrated local directory in place.

If upgrading from preview 2 or earlier, also read the preview 3 migration notes
for SQLite enrichment migration 0004 before opening the old data directory.

Deliberately deferred to 2.1

Version 2.0 does not claim full interface and publishing parity. The following
remain tracked for the 2.1 iteration:

• the secured loopback research ui API and local web application;
• collections and selective public projection, including HTML, JSON, RSS, and
  JSON Feed;
• publication preview and privacy-negative artifact verification;
• Pocket export, browser bookmark, canonical JSON/CSV import, and canonical
  export workflows;
• repository consolidation/governance completion; and
• multiple library profiles, repository switching, and multi-repository sync.

The hosted owner application is a private management surface, not a public
collection publication database. Do not put a private data repository,
credential, SQLite database, operation envelope, or pack into a public
repository.

Download and verify

Platform	Release asset
Linux GNU/glibc x86-64 (glibc 2.35 or newer)	research-v2.0.0-linux-amd64.tar.gz
Windows x86-64	research-v2.0.0-windows-amd64.zip
macOS Intel	research-v2.0.0-macos-amd64.tar.gz
macOS Apple Silicon	research-v2.0.0-macos-arm64.tar.gz

Download SHA256SUMS beside the selected archive and verify it before
extraction.

Linux:

sha256sum --check --ignore-missing SHA256SUMS

macOS:

shasum -a 256 --check --ignore-missing SHA256SUMS

Windows PowerShell:

Get-FileHash .\research-v2.0.0-windows-amd64.zip -Algorithm SHA256

The binaries are not code-signed or notarized. If the operating system does not
accept an archive, build the reviewed tag with the pinned toolchain instead of
weakening system-wide security:

git clone --branch v2.0.0 --depth 1 \
  https://github.com/ResearchPocket/researchpocket.github.io.git
cd researchpocket.github.io
cargo build --locked --release

The historical crates.io package is not the 2.0 installation channel. The V2
workspace contains unpublished internal domain and store crates, so use a
verified GitHub archive or build the exact tag from source.

Report a problem safely

Open a GitHub issue with the command, platform, exact error, and redacted
diagnostic output. Never attach a private database, GitHub or Firecrawl token,
protocol envelope, operation pack, credential file, or unredacted library
export to a public issue.

ResearchPocket 2.0.0-preview.4

ResearchPocket v2.0.0-preview.4

This preview makes a normal multi-edit synchronization flush create one
immutable GitHub operation-pack file and normally one commit, instead of one
file and commit for every local edit. The change is application-level transport
packing: Git history still has no role in choosing or merging library values.

The release is suitable for personal-library use and migration testing, but it
is not V2 general availability. Keep the private remote repository and local
library under your control, and retain a verified backup of any V1 source.

What changed

• Native and hosted-browser clients preserve every durable UpdateEnvelope
  byte-for-byte, then place two or more queued envelopes in one immutable,
  content-addressed operation pack at sync time.
• A single queued edit keeps the original direct operation-file format. A
  normal multi-edit flush adds one pack file and one GitHub Contents commit.
• Packs are bounded to 1,000 logical envelopes and 20 MiB. An exceptional larger
  queue is split deterministically instead of making an unbounded request.
• Pack path/body hashes, schema, library/device identity, member ordering,
  Base64, exact envelope bytes, payload hashes, protocol/schema/codec support,
  and Loro updates are validated before the local transaction commits.
• Applying a pack and acknowledging all of its member outbox rows is atomic.
  A malformed member or changed immutable path preserves the complete local
  queue and state.
• Direct files and pack members deduplicate by logical device/sequence identity;
  byte-identical delivery is idempotent and conflicting bytes stop sync.
• Upload timeouts, rate limits, server failures, and branch-head races retain
  every exact member for retry. No merge, rebase, force-push, mutable log, or Git
  conflict workflow is used.
• The hosted Sync tab continues to show every individual pending add, edit,
  favorite/tag change, delete, and restore even when those changes will travel
  in one pack.
• Existing direct operation files and repositories remain readable and are not
  rewritten or pruned.

The domain/CRDT schema remains version 2 and the synchronization protocol remains
version 1. operation-packs-v1 is a new required transport feature asserted by
each pack. The full decision and recovery rules are in
ADR 0003.

Required coordinated upgrade

Upgrade every native and browser client for one private library before allowing
the first preview 4 client to sync. Once an operation pack exists in the remote
repository, preview 3 and older clients intentionally stop when they encounter
the recognized unsupported object; they do not silently ignore packed saves or
upload stale state.

Recommended sequence:

1. Close every ResearchPocket CLI, TUI, owner-app tab, and capture process.
2. Make an offline filesystem backup of each native local data directory.
3. Install the preview 4 CLI on every native device and confirm its version.
4. Reload the hosted owner app so it receives the preview 4 shell.
5. Run one sync from each upgraded device.

research --version
research status
research sync run

There is no SQLite migration in this release. Existing local envelopes and
outbox rows remain unchanged. Do not delete existing operation files or squash
repository history. To keep using an older client, restore a pre-pack private
repository and matching local backup instead of editing protocol files by hand.

On macOS, reinstall the native capture association after replacing the binary
because the per-user application bridge contains its own copy:

research capture install
research capture status

Download and verify

Platform	Release asset
Linux GNU/glibc x86-64 (glibc 2.35 or newer)	research-v2.0.0-preview.4-linux-amd64.tar.gz
Windows x86-64	research-v2.0.0-preview.4-windows-amd64.zip
macOS Intel	research-v2.0.0-preview.4-macos-amd64.tar.gz
macOS Apple Silicon	research-v2.0.0-preview.4-macos-arm64.tar.gz

Verify SHA256SUMS and the selected archive before extraction. On Linux:

sha256sum --check --ignore-missing SHA256SUMS

On macOS:

shasum -a 256 --check --ignore-missing SHA256SUMS

On Windows, compare the matching checksum line with:

Get-FileHash .\research-v2.0.0-preview.4-windows-amd64.zip -Algorithm SHA256

The preview binaries are not code-signed or notarized. If the operating system
does not accept the archive, build the reviewed tag with the pinned toolchain
instead of weakening system-wide security:

git clone --branch v2.0.0-preview.4 \
  https://github.com/ResearchPocket/researchpocket.github.io.git ResearchPocket
cd ResearchPocket
cargo build --locked --release

Report defects with the command, platform, exact error, and redacted diagnostic
output. Never attach a private database, GitHub or Firecrawl token, protocol
update, operation pack, or unredacted library export to a public issue.

ResearchPocket 2.0.0-preview.3

ResearchPocket v2.0.0-preview.3

This preview makes browser capture richer without weakening ResearchPocket's
URL-first durability boundary. It also includes the hosted-library interaction,
mobile layout, and synchronization-visibility fixes merged since preview 2.

The release is suitable for personal-library use and migration testing, but it
is not V2 general availability. Keep the private remote repository and local
library under your control, and retain a verified backup of any V1 source.

What changed

• Firefox bookmarklet capture version 2 reads bounded title, description, and
  language metadata from the already-loaded page DOM. Version 1 capture URIs
  remain accepted.
• Optional native metadata enrichment always saves the URL first. The same
  transaction creates a durable local retry job, so offline pages, provider
  failures, or process interruption cannot discard a capture.
• The direct provider extracts public HTML title, description, and language with
  DNS pinning, redirect revalidation, private/special-address rejection, strict
  time/content/body limits, and no cookies, credentials, referrer, or proxy.
• Firecrawl is an explicit alternative through its small /v2/scrape REST API.
  ResearchPocket does not include a Firecrawl SDK package, disables provider
  cache storage, and discards returned Markdown after retaining normalized
  metadata.
• Firecrawl keys may come from FIRECRAWL_API_KEY or a separate per-library key
  file written through standard input. The file is created with owner-only mode
  on Unix; on Windows it inherits the selected data directory's access controls,
  so a custom data directory must itself be restricted to the owner. Keys never
  enter SQLite, CRDT updates, capture URIs, sync repositories, handler manifests,
  logs, or command output.
• Enrichment fills only still-missing title, excerpt, and language fields. It
  records exact field-revision preconditions, rejects stale results after
  concurrent URL/lifecycle changes, and keeps human clears, edits, and deliberate
  empty strings canonical after synchronization.
• Short-lived transactional job leases prevent two local CLI processes from
  making the same provider request concurrently; abandoned jobs become
  claimable again after lease expiry.
• research enrich status reports provider state and aggregate queue counts;
  failures expose only sanitized categories and stop after five attempts.
• The hosted Sync tab now explains every queued add/edit/delete/restore and the
  exact fields or tags that will upload, without exposing note/excerpt text.
• Mobile library tags scroll horizontally and remain usable as filters. The
  compact filters, sticky workspace controls, save modal, favorite treatment,
  and Firefox-mobile layout include the preceding preview fixes.

The SQLite migration is automatic and local-only. The domain/CRDT schema remains
version 2 and the remote synchronization protocol remains version 1, so existing
private sync repositories remain compatible.

Upgrade

Before the first v2.0.0-preview.3 command opens an existing
v2.0.0-preview.2 library, close the CLI, TUI, and any browser capture process,
then make an offline filesystem backup of the entire local data directory.
Opening the library applies SQLite migration 0004. Treat the migrated directory
as forward-only: to return to v2.0.0-preview.2, close ResearchPocket, restore
the complete pre-upgrade directory, and then restore the older binary. Do not
remove the migration row or enrichment table by hand. The remote protocol is
unchanged, so the private sync repository does not need a corresponding rollback.

Download and verify the archive for the current platform, replace the existing
binary at its stable location, and confirm the version:

research --version
research status

Reinstall the native capture association after replacing the binary. This is
required on macOS because the per-user application bridge contains its own copy:

research capture install
research capture status

Replace the Firefox bookmark's Location/URL with the complete single line from
the tagged repository's bookmarklet.js to use capture version 2. An old
version 1 bookmarklet continues to save URL/title data.

Optional metadata enrichment

Use the bounded direct provider for one save:

research add https://example.com/article --enrich direct

Enable it after future browser captures and inspect the durable queue:

research enrich configure direct --on-capture
research enrich status
research enrich run

Firecrawl is an explicit third-party disclosure: each enriched target URL is
sent to the configured service. Store a key without putting its value in shell
history or process arguments:

printf '%s' "$FIRECRAWL_API_KEY" | \
  research enrich configure firecrawl --api-key-stdin --on-capture
research enrich status

research enrich disable removes the local provider configuration and stored
key. It does not delete saves, synchronized updates, or historical local job
counts. No enrichment worker or synchronization server runs in the background;
capture attempts its configured job after the durable save, and enrich run
processes due retries explicitly.

Full-page HTML/Markdown archives, PDFs, and attachments are not stored in this
preview. Those bytes need a separately reviewed content-addressed object
protocol rather than being embedded in CRDT updates or SQLite projection rows.

Download and verify

Platform	Release asset
Linux GNU/glibc x86-64 (glibc 2.35 or newer)	research-v2.0.0-preview.3-linux-amd64.tar.gz
Windows x86-64	research-v2.0.0-preview.3-windows-amd64.zip
macOS Intel	research-v2.0.0-preview.3-macos-amd64.tar.gz
macOS Apple Silicon	research-v2.0.0-preview.3-macos-arm64.tar.gz

Verify SHA256SUMS and the selected archive before extraction. On Linux:

sha256sum --check --ignore-missing SHA256SUMS

On macOS:

shasum -a 256 --check --ignore-missing SHA256SUMS

On Windows, compare the matching checksum line with:

Get-FileHash .\research-v2.0.0-preview.3-windows-amd64.zip -Algorithm SHA256

The preview binaries are not code-signed or notarized. If the operating system
does not accept the archive, build the reviewed tag with the pinned toolchain
instead of weakening system-wide security:

git clone --branch v2.0.0-preview.3 \
  https://github.com/ResearchPocket/researchpocket.github.io.git ResearchPocket
cd ResearchPocket
cargo build --locked --release

Report defects with the command, platform, exact error, and redacted diagnostic
output. Never attach a private database, GitHub or Firecrawl token, protocol
update, or unredacted library export to a public issue.

ResearchPocket 2.0.0-preview.2

ResearchPocket v2.0.0-preview.2

v2.0.0-preview.1 was not published. Its binaries passed their smoke tests,
but Linux archive validation exposed a release-workflow pipe failure. This
preview carries the corrected archive gate and otherwise ships the reviewed
V2 launch described below.

This is the first installable preview of the V2 local-first product. It is meant
for real personal-library use and recovery testing, but it is not a general
availability release. Keep the private remote repository and the local library
under your control, and retain a copy of any V1 source database until its import
has been checked.

What is ready

• A V2-only CLI for initializing a library; adding, editing, finding, deleting,
  and restoring saved URLs; inspecting status; and emitting human, JSON, or
  NDJSON output.
• A read-only, repeatable importer for an existing V1 ResearchPocket SQLite
  library. The importer does not copy retired Pocket credentials.
• A keyboard-first terminal interface for local capture, curation, search,
  favorites, tags, deletion, and restoration.
• Native Firefox capture through the installed researchpocket:// handler and
  the project bookmarklet. Capture commits locally without needing a server,
  GitHub credential, or network connection.
• Private GitHub synchronization using immutable CRDT updates. Git stores and
  transports updates; Git merges and commit order never choose library values.
• A static hosted owner application with an offline IndexedDB replica, local
  editing, and private-repository synchronization. The public application shell
  contains no private library data.

ResearchPocket does not require a continuously running backend. The project
site and hosted owner entry point are available at
https://researchpocket.github.io/ResearchPocket/.

Download and verify

Download SHA256SUMS and the archive for the computer that will run the CLI:

Platform	Release asset
Linux GNU/glibc x86-64 (glibc 2.35 or newer)	research-v2.0.0-preview.2-linux-amd64.tar.gz
Windows x86-64	research-v2.0.0-preview.2-windows-amd64.zip
macOS Intel	research-v2.0.0-preview.2-macos-amd64.tar.gz
macOS Apple Silicon	research-v2.0.0-preview.2-macos-arm64.tar.gz

On Linux, verify the downloaded archive with:

sha256sum --check --ignore-missing SHA256SUMS

On macOS, use:

shasum -a 256 --check --ignore-missing SHA256SUMS

On Windows, compare the displayed hash with the matching line in
SHA256SUMS:

Get-FileHash .\research-v2.0.0-preview.2-windows-amd64.zip -Algorithm SHA256

The Unix archives preserve the executable bit. Extract an archive and place the
binary in a directory on PATH, for example:

tar -xzf research-v2.0.0-preview.2-linux-amd64.tar.gz
mkdir -p "$HOME/.local/bin"
install -m 0755 \
  research-v2.0.0-preview.2-linux-amd64/research \
  "$HOME/.local/bin/research"
research --version

On Windows, expand the zip and either run research.exe from its extracted
directory or add that directory to the user PATH.

The preview executables are not code-signed or notarized. macOS Gatekeeper and
Windows reputation checks may therefore warn about a downloaded binary. If the
operating system does not accept it, build the tagged source with the pinned
Rust toolchain rather than weakening system-wide security settings:

git clone --branch v2.0.0-preview.2 \
  https://github.com/ResearchPocket/ResearchPocket.git
cd ResearchPocket
cargo build --locked --release

Start a local library

research init
research add https://example.com/article --tag reading
research list
research search article
research tui

ResearchPocket stores the library in the platform application-data directory by
default. Use research status to inspect the selected library and pending
outbox. A separate library can be selected with --data-dir or
RESEARCHPOCKET_DATA_DIR.

To import a V1 library without changing its database:

research import v1 /path/to/v1/research.sqlite
research status

Review imported counts and representative saves before retiring the source.

Save from Firefox

Keep the installed binary in its long-term location, then register the local
capture handler:

research capture install
research capture status

Create a Firefox bookmark whose location is the single-line bookmarklet.js
from the tagged repository. Clicking it sends the current HTTP(S) URL and title
to the installed CLI. The save is durable locally before any synchronization.
Re-run research capture install after moving or upgrading the binary,
especially on macOS.

Connect private synchronization

Create or choose a private GitHub data repository. Use an expiring fine-grained
personal access token scoped only to that repository with Contents: read and write. Keep it out of shell history by reading it silently in Bash or Zsh and
remove it from the shell as soon as the sync finishes:

printf 'Fine-grained GitHub token: ' >&2
IFS= read -r -s RESEARCHPOCKET_GITHUB_TOKEN
printf '\n' >&2
export RESEARCHPOCKET_GITHUB_TOKEN
research sync connect OWNER/PRIVATE_REPOSITORY
research sync run
unset RESEARCHPOCKET_GITHUB_TOKEN
research status

Repeat the silent read and export in a new shell before a later sync. Run the
unset command after use even when a sync command reports an error.

Run research sync run --every 60 for an optional foreground periodic loop.
Network, rate-limit, credential, or branch-head failures leave pending updates
in the durable outbox for retry.

The hosted owner app asks for the same private repository and a separately
entered fine-grained token. By default the token remains only in JavaScript
memory; the explicit tab-only option uses sessionStorage.

Restore another device

First synchronize the source device until research status reports no pending
updates. On a clean device or a deliberately separate data directory:

research --data-dir /path/to/new/library init
printf 'Fine-grained GitHub token: ' >&2
IFS= read -r -s RESEARCHPOCKET_GITHUB_TOKEN
printf '\n' >&2
export RESEARCHPOCKET_GITHUB_TOKEN
research --data-dir /path/to/new/library \
  sync connect OWNER/PRIVATE_REPOSITORY
research --data-dir /path/to/new/library sync run
unset RESEARCHPOCKET_GITHUB_TOKEN
research --data-dir /path/to/new/library status

A pristine client adopts the remote library identity, keeps its own device
identity, applies the immutable update log, and rebuilds its local projection.
Do not upload or merge a live SQLite database as a synchronization shortcut.

Preview limitations

• Selective public collection publishing, feeds, and sanitized sharing are not
  implemented yet. The hosted site is an owner application, not a published
  copy of the private library.
• The secured loopback research ui server is not implemented. Use the CLI,
  TUI, or hosted owner application.
• Checkpoints and an installed background scheduler are not implemented. Update
  history is retained, and periodic native sync currently uses the foreground
  --every loop.
• This preview supports the V1 SQLite importer; browser-bookmark, JSON, CSV, and
  Pocket-export import commands are not part of this release.
• Release binaries are available only for the four platforms listed above and
  are not code-signed. The Linux asset targets GNU/glibc x86-64 with glibc 2.35
  as its minimum (the Ubuntu 22.04 build baseline); musl-only Linux, Linux ARM,
  and Windows ARM packages are not available yet.
• The crates.io package is not the installation channel for this preview. Use a
  verified GitHub release archive or build the tagged source.
• This is pre-GA software. Back up through a completed private sync before
  upgrading, and read later release notes for any migration requirement.

Report defects with the command, platform, exact error, and redacted diagnostic
output. Never attach a private database, GitHub token, protocol update, or
unredacted library export to a public issue.

v0.1.22

bump version