Adopt ``rmscene`` For .rm Read/Write (0005-rmscene-dependency)
==============================================================

Context
-------
Writing modern reMarkable ``.rm`` files (v6) involves a block-based format
with CRDT sequences and tagged blocks (TreeNode, SceneGroupItem, SceneLineItem,
RootText, etc.). Implementing a correct writer is non-trivial and requires a
robust encoder and stable schema knowledge. A prior exploration of a Go
codebase (``rm2pdf``) showed that while it parses v5, its v6 parsing and any
writing are not implemented, making it impractical to base a writer on it.

Decision
--------
Use the Python ``rmscene`` library as the canonical mechanism for reading and
writing ``.rm`` v6 files in this project.

- For generating notebooks/pages, ``rmfiles.notebook`` will build in-memory
  structures and call ``rmscene.write_blocks`` to produce ``.rm`` files.
- For inspection and future read flows, prefer ``rmscene.read_blocks`` and
  higher-level helpers.
- Keep local, minimal helpers only for convenience or data modeling; avoid
  re-implementing block encoders.

Consequences
------------
Positive
^^^^^^^^
- Leverages a maintained, specialized implementation for the v6 format.
- Reduces risk of subtle encoding bugs; faster path to working features.
- Aligns with existing tests and abstractions already using ``rmscene``.

Trade-offs
^^^^^^^^^^
- Introduces a runtime dependency, fetched from GitHub (network access needed).
- Upstream API or behavior changes can affect us if unpinned.
- Developers need a Python environment (already true for this repo).

Guidance For Development
------------------------
- Installation
  - Editable install: ``pip install -e .`` (installs ``rmscene`` from GitHub).
  - Network-restricted environments: pre-install ``rmscene`` from a wheel or
    pin a specific commit/tag in ``setup.py``/``requirements.txt`` as needed.

- Usage patterns
  - Write
    - Build blocks from our in-memory notebook and call
      ``rmscene.write_blocks(binary_io, blocks)``.
  - Read
    - Use ``rmscene.read_blocks(binary_io)`` to iterate blocks, or
      higher-level tree helpers if needed.

- Testing
  - Prefer golden tests using known-good ``.rm`` fixtures.
  - For generation tests, verify file presence, header bytes (``reMarkable``
    string), and basic structure via ``rmscene.read_blocks`` when available.

Follow-ups
----------
- We have pinned ``rmscene==0.7.0`` in ``setup.py`` and ``requirements.txt`` to
  ensure reproducible CI/local installs. Revisit the pin periodically to
  incorporate upstream fixes (consider pinning to a tag/commit if needed).
- Extend CLI with richer inspect commands powered by ``rmscene``.
- Document offline workflows (prebuilt wheels, internal mirrors) if needed.