Plan human-facing E2E coverage and document UX

Define stable test tiers and risk-ranked journeys across installed
commands, public Python APIs and the `Qt` chart.

Also,
- keep volatile subsystem deats out of adjacent iface guides
- require real `Qt` input and protocol-faithful offline services
- specify lifecycle ownership, CI tiers and acceptance gates

(this patch was generated in some part by `opencode` using `gpt-5.6-sol` (`openai`))

piker/cli/README.rst

@@ -0,0 +1,65 @@
+piker command-line guide
+========================
+
+Piker installs three human-facing entry points with different jobs:
+
+* ``piker`` is the main command group for broker, data, storage and UI tasks.
+* ``pikerd`` is the long-running root service supervisor.  Clients such as
+  ``chart`` connect to it, or start a service tree when none is running.
+* ``ledger`` is the separate trade-ledger and position-accounting tool.  Its
+  commands can contact brokers or update account data; it is not read-only.
+
+See the `project README <../../README.rst>`_ for installation and runtime context.
+
+Safe discovery and first run
+----------------------------
+
+From a checkout, these enter no broker, UI or account command body::
+
+    uv run piker --help
+    uv run piker chart --help
+    uv run pikerd --help
+    uv run ledger --help
+
+Explicit ``--help`` prints usage and exits 0.  Repeat it at each command level.
+
+A low-risk first runtime starts only the supervisor; stop it with ``Ctrl-C``::
+
+    uv run pikerd -l info
+
+It waits for client requests before starting broker or feed work.  Run this
+intentionally long-lived process in its own terminal.
+
+Root options come first
+-----------------------
+
+Click options precede the subcommand that consumes them.  ``--brokers``,
+``--loglevel``, ``--configdir`` and ``--pdb`` are ``piker`` root options::
+
+    uv run piker -l info -c /tmp/piker-profile chart <fqme>
+
+Create the configuration directory first.  Do not move ``-l`` or ``-c`` after
+``chart``; use ``piker chart --help`` for options owned by that subcommand.
+
+For isolation, set ``XDG_CONFIG_HOME`` before any Piker process.  ``piker -c``
+can also select an existing directory for that ``piker`` invocation::
+
+    export XDG_CONFIG_HOME=/tmp/piker-xdg
+    mkdir -p "$XDG_CONFIG_HOME/piker"
+    uv run piker -c "$XDG_CONFIG_HOME/piker" --help
+
+Output contracts
+----------------
+
+Parser errors are non-zero, but operational callbacks do not yet share one
+failure-code contract.  Tables, colors, help prose and logs are human output.
+Consume JSON only when that command advertises ``--json`` and pin automation to
+its tested schema.  No CLI-wide JSON or stdout/stderr stability is promised.
+
+Intentionally not guaranteed
+----------------------------
+
+Registry/service-list details, multiaddr syntax/routing, and storage commands,
+SHM identities and disk layouts are volatile and intentionally not guaranteed.
+Consult the running checkout; focused storage UX expectations live in
+`tests/test_store_cli.py <../../tests/test_store_cli.py>`_.

piker/ui/README.rst

@@ -0,0 +1,68 @@
+Qt chart guide
+==============
+
+The Qt chart is Piker's keyboard-first realtime market view.  Follow the
+`project README <../../README.rst>`_, include the UI group, then launch an FQME::
+
+    uv sync --group uis
+    uv run piker -l info chart btcusdt.spot.binance
+
+Use a market supported by your provider; a name without its provider suffix is
+rejected.  This is not an offline demo: launch may contact provider services
+and needs a Qt display.  Put root options before ``chart``; see
+`piker/cli/README.rst <../cli/README.rst>`_.
+
+Daemon lifetime
+---------------
+
+The chart looks for ``pikerd`` and starts a supervisor for its session if none
+is available.  To retain service state across chart restarts, run
+``uv run pikerd`` separately first.  That daemon has its own lifetime; stop it
+in its terminal.
+
+Keyboard journeys
+-----------------
+
+Keep focus on the chart or search pane whose action you want:
+
+* Search: press ``Ctrl-L`` (``L`` for "list" symbols), type, move with
+  ``Ctrl-J``/``Ctrl-K`` (or ``Ctrl-Down``/``Ctrl-Up``), then ``Enter``.
+  ``Ctrl-C`` or ``Ctrl-Space`` returns focus to the chart.
+* Chart: use the wheel to zoom and press ``R`` to restore the default view.
+  ``Ctrl-I`` and ``Ctrl-O`` provide keyboard zoom in and out.
+* Gaps: press ``Ctrl-G`` on the focused realtime or history chart to toggle
+  chart-local OHLC gap markers for that pane and timeframe.
+* Orders: hold ``F`` ("fill") for buy, ``D`` ("dump") for sell or ``A`` for
+  an alert to stage at the cursor.  Buy/sell default to dark; add ``S`` or
+  ``Ctrl`` for live.  A left-click submits.  ``C`` or ``Delete`` cancels under
+  the cursor; quick ``cc`` ("complete clear") asks to cancel all orders.
+
+These are real controls.  Confirm the mode label, account and paper/live setup;
+a live account can send a real order.
+
+Closing safely
+--------------
+
+Closing the main window saves geometry and sends ``SIGINT`` to the chart process
+so its async runtime can unwind.  Do not use ``MainWindow.close()`` as generic
+cleanup inside another app or test runner: the signal targets the whole process.
+The full in-process test tier therefore needs a dedicated shutdown seam.
+
+Testing contract
+----------------
+
+The intended default automated gate is layered and deterministic:
+
+* Drive real PyQt6/PyQtGraph objects with real Qt key and mouse events through
+  production event filters.
+* Use synthetic market data and deterministic feed, search, EMS and service
+  boundaries; assert visible state, scene ownership and clean teardown.
+* Keep screenshots as failure artifacts, not pixel or visual goldens.
+* Keep live brokers, credentials, network feeds and compositor qualification
+  out of the default gate.
+
+Current `gap tests <../../tests/test_gap_overlays.py>`_ send a real ``QKeyEvent``
+through ``Ctrl-G`` and use real graphics scenes.  The actor case stubs rendering,
+so this is integration evidence, not full chart E2E.  Intended tiers and close
+work live in the `pytest-qt chart plan
+<../../plans/opencode/pytest-qt-chart-ui-e2e.md>`_.