cellpy 2.1.3.post1__tar.gz → 2.1.3.post3__tar.gz

cellpy-2.1.3.post3/.issueflows/01-current-issues/issue985_original.md

@@ -0,0 +1,14 @@
+# Issue #985: Iterative fixes: improve ica docs
+
+Source: https://github.com/jepegit/cellpy/issues/985
+
+## Original issue text
+
+Interactive `/iflow-fix` session to improve ICA (incremental capacity analysis) documentation.
+
+Individual small fixes are recorded in the issue-flow status markdown and landed together via `/iflow-close`.
+
+Scope (docs-only polish, not a redesign):
+- Align public docs with the 2.1 `cellpy.ica` API (`dqdv` / `dvdq` / `IcaOptions`)
+- Fill gaps (DVA, plotting/collect, agents guide, API page)
+- Fix stale `cellpy.utils.ica` / 1.x helper references where they confuse readers

cellpy-2.1.3.post3/.issueflows/01-current-issues/issue985_status.md

@@ -0,0 +1,16 @@
+# Issue #985 status
+
+Interactive `/iflow-fix` session: improve ICA docs.
+
+- [ ] Done
+
+## Iterative fixes log
+
+- 2026-09-02 — Add `docs/guides/ica.md` how-to (`dqdv` / `dvdq` / `ica_plot` / collect) and wire it into `zensical.toml` + `docs/guides/index.md`.
+- 2026-09-02 — Expand `docs/api/ica.md` as the ICA/DVA hub (preferred import, `to_wide`, plot/collect table, `IcaOptions` name clash).
+- 2026-09-02 — Fix API index “Where to look”: ICA and Plotting were buried under Utils; add DVA to `docs/api/collect.md`; point `docs/api/plotting.md` at `ica_plot` / `dva_plot`.
+- 2026-09-02 — Agent recipe: `docs/getting_started/agents.md` + root `AGENTS.md` quick fact; basic-usage + 2.1 migration pointers.
+- 2026-09-02 — Tutorial: prefer `from cellpy import ica`; add DVA/plotting closer in `examples/04_incremental_capacity_analysis.ipynb` and the rendered docs copy.
+- 2026-09-02 — Stale docstrings: drop “`dq` until 2.1” from `cellpy/collect/ica.py`; update `cellpy/utils/ica.py` re-export note; fundamentals no longer call ICA a utils-only tool.
+- 2026-09-02 — How to use `IcaOptions`: construct the dataclass, pass `options=`, `.replace()`, and stacked keyword overrides. Added to `docs/guides/ica.md` (plus collect-side `IcaOptions`), `docs/api/ica.md`, the agents recipe, `AGENTS.md`, and the ICA tutorial notebook / rendered page.
+- 2026-09-02 — Docs CI: drop the `[cellpy.ica.DVA_DEFAULTS]` autoref in `docs/guides/ica.md` (module constant has no mkdocstrings identifier; zensical reported "1 issue found").

{cellpy-2.1.3.post1/.issueflows/02-partly-solved-issues → cellpy-2.1.3.post3/.issueflows/03-solved-issues}/issue891_status.md

@@ -1,6 +1,10 @@
 # Issue #891 — status
 
-- [ ] Done
+- [x] Done
+
+Closed out 2026-08-29 by `/iflow-doctor`: the remaining work below all landed,
+but this file was never updated when the last PR merged. GitHub issue #891 was
+closed 2026-08-16 (milestone v.2.1.3).
 
 ## What's done
 
@@ -18,20 +22,23 @@
 
 ## Remaining work
 
-- [ ] PR 2 — global flags (`--quiet` / `--verbose` / `--no-color`), failures to
+None — every item below shipped:
+
+- [x] PR 2 — global flags (`--quiet` / `--verbose` / `--no-color`), failures to
       stderr, exit codes 0/1/2, delete the hand-rolled usage block in `run`;
       regenerate `tests/data/cli_surface.json` in the same commit.
-- [ ] PR 3 — `info` / `info --check`.
-- [ ] PR 4 — `setup` (drop the parameter dump, make `--silent` real).
-- [ ] PR 5 — copy pass over the remaining commands; fix the `f[cellpy]` literal
+      → `be37069c` (#915).
+- [x] PR 3 — `info` / `info --check`. → `4a190122` (#918), with `d502fe5a`
+      (#922) relaxing the check test's machine assumptions.
+- [x] PR 4 — `setup` (drop the parameter dump, make `--silent` real).
+      → `2ee02193` (#934).
+- [x] PR 5 — copy pass over the remaining commands; fix the `f[cellpy]` literal
       and the `deiced` typo; remove the stray `print()` calls.
-- [ ] Register the new essential tests in
-      [test-registry.md](../04-designs-and-guides/test-registry.md). Deferred
-      out of PR 1 only because the concurrent #912 session has uncommitted rows
-      in that file; staging it would have swept their work into this commit.
-      Rows to add (`tests/test_cli_ui.py`, essential/always, code under test
-      `cli_ui.Reporter`, issue #891) plus
-      `test_cli_light_import.py::test_importing_cli_ui_does_not_import_rich`.
+      → `2ee02193` (#934).
+- [x] Register the new essential tests in
+      [test-registry.md](../04-designs-and-guides/test-registry.md). The
+      registry now carries 16 rows tagged #891, so the #912 collision noted
+      below resolved itself.
 
 ## Notes
 

cellpy-2.1.3.post3/.issueflows/03-solved-issues/issue939_original.md

@@ -0,0 +1,56 @@
+# Issue #939: from_cells silently drops values that are not cells
+
+Source: https://github.com/jepegit/cellpy/issues/939
+
+## Original issue text
+
+`cellpy.collect.from_cells` does not validate the mapping it is given. A value that is not a `CellpyCell` — a `Path`, an `int`, anything — simply does not appear downstream: no exception, no warning, not even a log line.
+
+Reproduced on **cellpy 2.1.3** (Python 3.13, clean `uv run --script` environment).
+
+```python
+# /// script
+# requires-python = ">=3.13"
+# dependencies = ["cellpy"]
+# ///
+import warnings
+warnings.simplefilter("ignore")
+
+from cellpy.collect import collect_summaries, from_cells
+from cellpy.utils import example_data
+
+cell = example_data.cellpy_file()
+
+with warnings.catch_warnings(record=True) as caught:
+    warnings.simplefilter("always")
+    batch = from_cells({
+        "good": cell,
+        "a_path": example_data.rate_file(),   # returns a Path, not a cell
+        "an_int": 42,
+    })
+    print("warnings:", [str(w.message) for w in caught])
+
+collection = collect_summaries(batch, columns=("discharge_capacity_gravimetric",))
+print("3 entries in ->", collection.data["cell"].unique().to_list(), "out")
+```
+
+```text
+warnings: []
+3 entries in -> ['good'] out
+```
+
+## Why it is worth guarding
+
+The failure surfaces to a *user* as a chart with fewer lines than they have cells, which reads as a data problem rather than a type error. Nothing points back at the call that dropped them.
+
+The easy way in is real rather than hypothetical: `example_data.cellpy_file()` returns a **cell** while its sibling `example_data.rate_file()` returns a **path**. Adjacent functions, same naming family, asymmetric return types — and `from_cells` accepts the mistake without comment. Any code that builds the mapping from something dynamic (a file picker, a glob, a journal) can hit this and never know.
+
+## Suggestion
+
+Raise on a value that is not a `CellpyCell`, naming the offending keys — or, if silence is deliberate for some caller, at minimum a warning listing what was skipped. Silently narrowing a collection is unlikely to be what anyone meant.
+
+## Context
+
+Found while writing task-shaped guides for building on cellpy, in a repository where every documentation code block is executed by CI — this turned up as a print that did not match its expected output. Two independent agents given the same "load these cells" task hit it, and both reported the `rate_file()` / `cellpy_file()` asymmetry as the thing most likely to burn someone.
+
+Notes: https://github.com/cellpy/cellpy-simple-gui/blob/main/CELLPY_PAINPOINTS.md (§34)

cellpy-2.1.3.post3/.issueflows/03-solved-issues/issue939_plan.md

@@ -0,0 +1,172 @@
+# Plan — Issue #939: `from_cells` silently drops values that are not cells
+
+## Goal
+
+Make a non-cell value passed to `from_cells` fail loudly and by name, and make
+`collect_summaries` say something when it narrows a collection, so a user never
+again sees "a chart with fewer lines than I have cells" with no explanation.
+
+## Findings (reproduced on `master` @ `82ab7e03`)
+
+The issue's script still fails exactly as reported — three entries in, one out,
+zero warnings:
+
+```text
+warnings: []
+3 entries in -> ['good'] out
+```
+
+The drop is **not** in `from_cells`. `Batch.from_cells` writes all three labels
+into `journal.pages` and hands all three values to `CellStore.from_cells`
+unexamined ([`cellpy/batch/facade.py`](../../cellpy/batch/facade.py), the
+`from_cells` classmethod). The narrowing happens later, in
+`collect_summaries`: for each label it calls `ops.extract_cell_summary`, which
+reads `getattr(getattr(cell, "data", None), "summary", None)`
+([`cellpy/collect/_summary_ops.py`](../../cellpy/collect/_summary_ops.py)). A
+`Path` or an `int` has no `.data`, so that resolves to `None`, the function
+returns `None`, and [`cellpy/collect/summary.py`](../../cellpy/collect/summary.py)
+hits `if frame is None or frame.height == 0: continue` — a bare `continue` with
+no log line.
+
+Two consequences worth designing around:
+
+- `collect_summaries` **already knows** which cells contributed: it builds an
+  `included` list and stores it on `CollectionMeta.cells_included`. The
+  information needed for a warning is already computed and simply never used
+  for feedback.
+- `collect_cycles` does **not** share the bug — it calls
+  `cell.get_cycle_numbers()`, so a `Path` raises `AttributeError` there. Only
+  the summary path is silent.
+
+### What counts as "a cell"
+
+The issue asks to raise on anything that is not a `CellpyCell`. A literal
+`isinstance(value, CellpyCell)` check is the wrong instrument here: the whole
+codebase duck-types cells as "something with `.data`"
+(`plotutils.py`, `collect/_summary_ops.py`, `batch/qc.py`, `batch/aggregate.py`,
+`batch/facade.py`), and every cell stub in the test-suite
+(`_SummaryCell`, `_StubCell`, the local `_Cell` classes) is a `SimpleNamespace`
+holder, not a `CellpyCell`. A strict check would break `tests/test_from_cells.py`
+wholesale while adding no safety a duck-type check does not already give:
+
+| value | `hasattr(v, "data")` |
+| --- | --- |
+| `CellpyCell` | True |
+| stub cell | True |
+| `Path` | False |
+| `int` / `str` / `None` | False |
+
+So the guard is: **the value must expose `.data`** — the same contract every
+downstream consumer already relies on.
+
+## Constraints
+
+- Validate in `Batch.from_cells` only. `CellStore.from_cells` is the internal
+  loader path (`_store_from_result`, `benchmarks/conftest.py`,
+  `tests/test_batch_v3_runner.py` passes `None` there deliberately) and must
+  keep accepting whatever the runner produces.
+- Duck-type, do not `isinstance`-check against `CellpyCell` (see above). This
+  also avoids importing `cellreader` into `batch.facade` at module scope.
+- Back-compat: no production caller of `Batch.from_cells` exists outside the
+  two public wrappers, and no doc example passes a non-cell, so raising is not
+  a breaking change for any working code.
+- Keep the PR to the silent-drop story. The `example_data.cellpy_file()` (cell)
+  vs `example_data.rate_file()` (path) asymmetry the reporter calls out is a
+  public-API rename and is explicitly out of scope — it is addressed here only
+  by making the error message name that mistake.
+
+### Prior art
+
+- `_known_cells_hint` + `_MAX_LISTED_CELLS` in
+  [`cellpy/batch/facade.py`](../../cellpy/batch/facade.py) — added for #950
+  (merged as #973) to name a batch's cells in an unknown-label error. Same
+  file, same problem shape (bad label / bad value), so **mirror** its style:
+  truncate long lists at 8 entries with a total count.
+- `mark_as_bad` raises `ValueError` for an unknown label while `drop` warns
+  (#950). Precedent for the raise-vs-warn split used below.
+- `_warn_ignored_export_kwargs` in the same file — the project's shape for a
+  `UserWarning` that names the offending keys.
+- `CollectionMeta.cells_included` in
+  [`cellpy/collect/summary.py`](../../cellpy/collect/summary.py) — the existing
+  included/excluded bookkeeping to reuse rather than recompute.
+- Toolbox (`.issueflows/00-tools/`): nothing applicable
+  (`scan_member_usage.py`, `scan_hardcoded_headers.py`, `migrate_prms_calls.py`
+  are migration scanners). No `graphify-out/`, so grep-only.
+
+## Approach
+
+**1. Raise in `Batch.from_cells` (the fix the issue asks for).**
+
+After `cell_map` is built (so it covers both the mapping and the sequence
+form), collect every label whose value has no `.data` attribute and raise a
+single `ValueError` naming all of them with their types, in the style of
+`_known_cells_hint`:
+
+```
+from_cells got 2 values that are not cells: 'a_path' (PosixPath), 'an_int' (int).
+A cell is what cellpy.get(...) / example_data.cellpy_file() returns; a path is not.
+```
+
+One error listing every offender, not one per value, so a user fixing a
+dict-comprehension sees the whole problem at once. When an offender is a
+`str`/`Path`, append the `cellpy.get(...)` hint — that is the reported trap.
+
+**2. Warn in `collect_summaries` when it narrows.**
+
+Track the labels that were iterated but produced no frame, excluding those
+skipped deliberately by `only_selected`, and emit one `UserWarning` naming
+them when the list is non-empty. This is the guard that also covers cells that
+came from a journal and simply have an empty summary — the case `from_cells`
+validation cannot see.
+
+The raise/warn split follows #950: a constructor given the wrong type is a
+programming error (raise); a collector finding one cell with nothing to
+contribute is a data condition the caller may legitimately continue past
+(warn).
+
+## Files to touch
+
+| Path | Change |
+| --- | --- |
+| `cellpy/batch/facade.py` | Validate `cell_map` in `Batch.from_cells`; raise `ValueError` naming offending labels + types. Reuse `_MAX_LISTED_CELLS` truncation style; add a small `_non_cell_hint` helper next to `_known_cells_hint`. |
+| `cellpy/collect/summary.py` | Record skipped labels alongside `included`; emit one `UserWarning` when cells were dropped for want of a summary. |
+| `tests/test_from_cells.py` | New tests: the issue's exact mapping raises and names both bad keys; a `Path` value gets the `cellpy.get` hint; the sequence form is validated too; valid stub cells still build a batch (regression guard on the duck-type choice). |
+| `tests/test_collect.py` | New test: a batch containing a summary-less cell warns and names it, and the good cells still come through. |
+| `docs/getting_started/agents.md` | Update the `from_cells` guidance to state that non-cell values now raise. |
+| `AGENTS.md` | One clause on the same in the batch bullet (per the agent-docs convention in `this-project.md`). |
+| `.issueflows/04-designs-and-guides/batch-load-orchestrator.md` | Extend the "Feedback on unknown labels (#950)" section with the #939 raise/warn decision, so the two live together. |
+| `.issueflows/04-designs-and-guides/test-registry.md` | Register the new essential tests. |
+| `HISTORY.md` | `[Unreleased]` bullet (written in the `/iflow-close` commit). |
+
+## Test strategy
+
+Per [`this-project.md`](../04-designs-and-guides/this-project.md): `uv run pytest`,
+never bare `python`, never conda.
+
+- New tests carry `@pytest.mark.essential` — they guard a public entry point
+  that app-building agents rely on, which is the documented bar for the marker.
+- Targeted first: `uv run pytest tests/test_from_cells.py tests/test_collect.py -q`.
+- Then the merge gate: `uv run pytest -m essential`.
+- Then the full suite: `uv run pytest` — specifically to catch any existing
+  test that trips the new `collect_summaries` warning (the main regression risk
+  in this change; see Open questions).
+- Manual: re-run the issue's own script and show it now raises instead of
+  printing `3 entries in -> ['good'] out`.
+
+## Open questions
+
+1. **Is the `collect_summaries` warning too noisy?** It is the part of this
+   change that can touch unrelated tests, since any fixture whose cell has an
+   empty summary would start warning. My recommendation is to keep it and fix
+   the handful of call sites if the full suite turns any up, because
+   downgrading it to `logging.debug` would recreate exactly the silence #939 is
+   about. If the full run shows this is widespread, I will report back before
+   forcing it through.
+2. **Raise or warn in `from_cells`?** Plan says raise, per the issue's stated
+   preference and the #950 precedent. Say so now if you would rather it warn
+   and keep going.
+3. **Follow-ups deliberately not in this PR:** `collect_cycles` reports
+   `cells_included=list(batch.cells)` (every label, not the contributing ones),
+   which is the same bookkeeping gap in the sibling collector; and the
+   `example_data` return-type asymmetry. Both can be issues of their own if you
+   want them.

cellpy-2.1.3.post3/.issueflows/03-solved-issues/issue939_status.md

@@ -0,0 +1,57 @@
+# Status — Issue #939: `from_cells` silently drops values that are not cells
+
+- [x] Done
+
+Branch: `939-from-cells-validation`
+PR: https://github.com/jepegit/cellpy/pull/974 (#974, draft)
+Plan: [issue939_plan.md](issue939_plan.md)
+
+## What's done
+
+- Reproduced on `master` @ `82ab7e03` (3 cells in, 1 out, no warnings).
+- Located the real drop site: not `from_cells`, but the bare `continue` in
+  `collect_summaries` after `extract_cell_summary` returns `None` for a value
+  with no `.data`.
+- `Batch.from_cells` now raises `ValueError` naming every value that is not a
+  cell and the type that arrived, with an extra `cellpy.get(path)` hint when an
+  offender is a path or a string (the reported `rate_file()` /`cellpy_file()`
+  trap). Covers the mapping and the sequence form.
+- `collect_summaries` now warns (`UserWarning`) and names cells that
+  contributed no rows, reusing the `included` bookkeeping it already kept for
+  `CollectionMeta.cells_included`. Cells skipped by `only_selected` are not
+  reported — those are deliberate.
+- "Is a cell" is duck-typed on `.data` asked of the **type**, not the instance:
+  `CellpyCell.data` is a property raising `NoDataFound` until something is
+  loaded, so an instance-level `hasattr` would answer "not a cell" (and raise)
+  for a legitimately empty cell. A strict `isinstance(value, CellpyCell)` was
+  rejected because every cell stub in the suite is a `SimpleNamespace`.
+- 6 new tests (4 in `test_from_cells.py`, 2 essential + 1 unmarked in
+  `test_collect.py`), registered in `test-registry.md`.
+- Docs: `docs/getting_started/agents.md` (new `from_cells` guidance), root
+  `AGENTS.md` bullet, `batch-load-orchestrator.md` design note. Also repaired
+  an orphaned list item in that design doc left by the #950 edit.
+
+## Deviation from the plan
+
+None on substance. Both open questions from the plan were settled with
+evidence rather than a guess:
+
+1. **Is the `collect_summaries` warning noisy?** No. A full run with
+   `-W always::UserWarning` records the new message **zero** times across
+   1744 tests, while still capturing other `UserWarning`s (e.g. the #962
+   batch-load warning). The plan's fallback — downgrading it to a debug log —
+   was not needed.
+2. **Raise or warn in `from_cells`?** Raise, as planned and confirmed.
+
+## Test results
+
+- `uv run pytest tests/test_from_cells.py tests/test_collect.py` — 59 passed.
+- `uv run pytest -m essential` — passed.
+- `uv run pytest` (full) — 1744 passed, 17 skipped, 15 xfailed, 1 xpassed,
+  0 failures.
+- `flake8` / `black`: no new findings; the remaining ones are present on
+  `master` for the same files.
+
+## Remaining work
+
+- None. Ready for `/iflow-close` (HISTORY bullet lands in the close commit).

cellpy-2.1.3.post3/.issueflows/03-solved-issues/issue950_original.md

@@ -0,0 +1,46 @@
+# Issue #950: b.mark_as_bad and  b.drop_cells_marked_bad() not working
+
+Source: https://github.com/jepegit/cellpy/issues/950
+
+## Original issue text
+
+Running:
+`b.mark_as_bad("20260515_sig002_04_fccc")
+b.mark_as_bad("20260515_sig002_06_fccc")
+b.mark_as_bad("20260515_sig002_10_fccc")
+b.drop_cells_marked_bad()`
+and then
+`b.combine_summaries()` or `b.plot()`
+creates this error:
+
+---------------------------------------------------------------------------
+KeyError                                  Traceback (most recent call last)
+Cell In[32], [line 2](vscode-notebook-cell:?execution_count=32&line=2)
+      1 # Plot the charge capacity and the C.E. (and resistance and rate) vs. cycle number (standard plot)
+----> [2](vscode-notebook-cell:?execution_count=32&line=2) b.plot(rate=True, ir=True, direction="discharge", ce_range=[0,130])
+
+File ~\AppData\Local\miniconda3\envs\cellpy213\Lib\site-packages\cellpy\batch\facade.py:354, in Batch.plot(self, backend, show, **kwargs)
+    350 def plot(self, backend: str | None = None, show: bool = False, **kwargs) -> Any:
+    351     from cellpy.plotting.batch_summary import batch_summary_plot
+    353     return batch_summary_plot(
+--> [354](https://file+.vscode-resource.vscode-cdn.net/c%3A/Users/IFE12959/cellpy_data/notebooks/Signal-2/2026_08_25_Analysis_213/~/AppData/Local/miniconda3/envs/cellpy213/Lib/site-packages/cellpy/batch/facade.py:354)         _LegacyExperimentAdapter(self.journal, self._store),
+    355         backend=backend,
+    356         show=show,
+    357         **kwargs,
+    358     )
+
+File ~\AppData\Local\miniconda3\envs\cellpy213\Lib\site-packages\cellpy\batch\facade.py:410, in _LegacyExperimentAdapter.__init__(self, journal, store)
+    408 per_cell: dict[str, Any] = {}
+    409 cycle_col = get_headers_summary().cycle_index
+--> [410](https://file+.vscode-resource.vscode-cdn.net/c%3A/Users/IFE12959/cellpy_data/notebooks/Signal-2/2026_08_25_Analysis_213/~/AppData/Local/miniconda3/envs/cellpy213/Lib/site-packages/cellpy/batch/facade.py:410) for label, cell in store.items():
+    411     summary = getattr(getattr(cell, "data", None), "summary", None)
+    412     if summary is None:
+
+File <frozen _collections_abc>:883, in ItemsView.__iter__(self)
+    881 def __iter__(self):
+...
+     47     self._cache[label] = cell
+     48     return cell
+---> [49](https://file+.vscode-resource.vscode-cdn.net/c%3A/Users/IFE12959/cellpy_data/notebooks/Signal-2/2026_08_25_Analysis_213/~/AppData/Local/miniconda3/envs/cellpy213/Lib/site-packages/cellpy/batch/store.py:49) raise KeyError(label)
+
+KeyError: '20260515_sig002_04_fccc'

cellpy-2.1.3.post3/.issueflows/03-solved-issues/issue950_plan.md

@@ -0,0 +1,152 @@
+# Plan: #950 `mark_as_bad` / `drop_cells_marked_bad` not working
+
+## Goal
+
+Close the gap behind [#950](https://github.com/jepegit/cellpy/issues/950): the
+reported `KeyError` crash is already fixed on `master` but unreleased, and the
+flow that produced it is still untested. Add the missing regression cover and
+remove the remaining reason a user reports this as "not working" — marking or
+dropping an unknown label is a completely silent no-op.
+
+## Findings (verified on `master`, not assumed)
+
+1. **The reported crash no longer reproduces.** #952 gave `CellStore` a real
+   `remove` and pointed `Batch.drop` at it. Replaying #950's flow (mark three
+   cells bad → `drop_cells_marked_bad()` → `summaries` / `experiment` adapter)
+   on `master` succeeds for both a loaded store (`Batch.from_cells`) and a lazy
+   loader store.
+2. **The fix is unreleased.** Latest tag is `v2.1.3.post1`; the #952 bullet sits
+   under `## [Unreleased]` in `HISTORY.md`. The reporter's traceback comes from
+   `envs/cellpy213`, i.e. 2.1.3 — before the fix. #950 and #952 are the same
+   crash seen from different versions.
+3. **#950's exact path is untested.** `test_drop_cells_marked_bad`
+   (`tests/test_batch.py`) uses a journal-only batch with an empty store and
+   asserts `cell_names` only. `test_drop_loaded_cell_forgets_store_label`
+   (`tests/test_batch_v3_facade.py`) covers `drop`, not
+   `drop_cells_marked_bad`, and does not touch `combine_summaries`. Nothing
+   exercises *marked-bad drop on a loaded batch → summaries / plot adapter*, so
+   the #952 fix can regress on precisely the reported flow without CI noticing.
+4. **A real, still-unfixed defect: silent no-op on an unknown label.**
+   `b.mark_as_bad("typo")` accepts any string, warns nothing, and records it in
+   `session["bad_cells"]`. `drop_cells_marked_bad()` then skips it (guarded by
+   `if label in self.journal.cell_names`) and returns silently — nothing
+   dropped, no exception, no warning, no log line. `b.drop("typo")` is likewise
+   a silent no-op. With cell names like `20260515_sig002_04_fccc`, a mistyped
+   or stale label is the most likely way a user reaches "it does not work"
+   without a traceback.
+5. **Stale `bad_cells` after a drop is *not* a bug.** Dropped labels stay in
+   `session["bad_cells"]` by design: `mark_as_bad` is the persistent record
+   that `batch.load(..., drop_bad_cells=True)` replays on the next session.
+   Pruning it would break that documented contract.
+
+## Constraints
+
+- `mark_as_bad` stays a session flag: it must not drop, load, or flip
+  `selected` (contract set by #952).
+- `_finalize` calls `drop_cells_marked_bad()` on **every** `batch.load` with
+  `drop_bad_cells=True` (the default). Anything raised from that method breaks
+  loading a journal whose `bad_cells` names an already-removed cell, so the
+  drop path must stay non-fatal.
+- Do not prune `session["bad_cells"]` (finding 5).
+- No collectors / plot-adapter rewrite — that stays Epic B.
+- New merge-gating tests carry `@pytest.mark.essential` and get rows in
+  [test-registry.md](../04-designs-and-guides/test-registry.md).
+- Public batch-surface change → update
+  [`docs/getting_started/agents.md`](../../docs/getting_started/agents.md) and
+  the short root `AGENTS.md` batch bullet in the same PR (#682 convention from
+  [this-project.md](../04-designs-and-guides/this-project.md)).
+- Test command is `uv run pytest`; no conda.
+
+### Prior art
+
+- `CellStore.remove` / `unload` — [`cellpy/batch/store.py`](../../cellpy/batch/store.py):
+  `remove` drops `_cache` / `_loaders` / `_labels`, `unload` is cache-only.
+  Both treat a missing label as a no-op. Reuse as is; the new feedback belongs
+  in the facade, which knows the journal, not in the store.
+- `Batch.drop` / `drop_cells_marked_bad` / `mark_as_bad` —
+  [`cellpy/batch/facade.py`](../../cellpy/batch/facade.py): the three call
+  sites to change.
+- `_finalize` — same file: the load-path caller that forces "warn, never
+  raise" on the drop side.
+- `summary_collector` unknown-family rejection —
+  `collect/collector.py::_family_options`, registered as
+  `test_summary_collector_rejects_an_unknown_family` (#927): the codebase
+  already raises `ValueError` with a valid-name list for a bad user-supplied
+  key. Mirror that shape rather than inventing a new one.
+- Anti-silent-failure line of work — #961 (named `env_file` in remote-auth
+  errors), #962 (`load` no longer treats a filefinder miss as success),
+  and open #938 / #939. This change is the batch-facade instance of the same
+  theme; match their wording style (say what happened, name the labels, point
+  at what to inspect).
+- `warn_once` — [`cellpy/_deprecation.py`](../../cellpy/_deprecation.py): for
+  deprecations, not for per-call user feedback. Use a plain `UserWarning` with
+  `stacklevel=2`, as `_finalize` does.
+- Toolbox: nothing in `.issueflows/00-tools/` applies. Graph: no
+  `graphify-out/`, so grep-only.
+
+## Approach
+
+1. **Regression test for the reported flow** (the part that guards #952 on
+   #950's exact path): loaded three-cell batch → `mark_as_bad` twice →
+   `drop_cells_marked_bad()` → assert `cell_names`, `list(b.cells)` and
+   `pages` agree, and that `combine_summaries()` and the `b.experiment`
+   adapter (the `plot()` crash site) both succeed. Essential.
+2. **Fail fast on the mark side.** `mark_as_bad(label)` raises `ValueError`
+   when `label` is not in `journal.cell_names`, naming the label and listing
+   the known names (truncated for large batches). This is direct interactive
+   user input, it is not on the load path, and nothing downstream benefits
+   from flagging a cell that does not exist.
+3. **Warn, never raise, on the drop side.** `drop_cells_marked_bad()` emits one
+   `UserWarning` naming any `bad_cells` entries it could not drop, and returns
+   normally — safe inside `_finalize`. `drop(label)` warns on an unknown label
+   for the same reason (it is also called internally).
+4. **Record the contract** in
+   [batch-load-orchestrator.md](../04-designs-and-guides/batch-load-orchestrator.md),
+   next to the existing #952 "same-session `drop` vs `unload`" subsection.
+5. **Docs**: one line in the `agents.md` mark/drop recipe and the root
+   `AGENTS.md` batch bullet describing the raise-vs-warn split.
+6. **`HISTORY.md`**: `[Unreleased]` bullet for #950 at `/iflow-close`. The
+   crash itself is already covered by the #952 bullet — do not double-report
+   it as a second fix.
+
+## Files to touch
+
+| Path | Change |
+| --- | --- |
+| `cellpy/batch/facade.py` | `mark_as_bad` raises on unknown label; `drop` / `drop_cells_marked_bad` warn instead of silently skipping. |
+| `tests/test_batch_v3_facade.py` | #950 regression (loaded marked-bad drop → summaries + adapter); unknown-label raise / warn tests. |
+| `.issueflows/04-designs-and-guides/batch-load-orchestrator.md` | Feedback contract next to the #952 note. |
+| `.issueflows/04-designs-and-guides/test-registry.md` | Rows for the new essential tests. |
+| `docs/getting_started/agents.md` | Mark / drop recipe gains the error-behaviour line. |
+| `AGENTS.md` | Batch bullet, only if it stays short. |
+| `HISTORY.md` | `[Unreleased]` bullet (written at close). |
+
+## Test strategy
+
+```bash
+uv run pytest tests/test_batch_v3_facade.py tests/test_batch.py -k "drop or mark or bad"
+uv run pytest -m essential
+```
+
+The second command is the CI Tier-1 merge gate. `test_drop_cells_marked_bad`
+(`tests/test_batch.py`) and `test_mark_as_bad_and_drop`
+(`tests/test_batch_v3_facade.py`) both mark labels that exist, so step 2 should
+leave them green; if either goes red, that is a signal the raise is too strict
+and the open question below needs the other answer.
+
+## Open questions
+
+1. **Raise or warn when `mark_as_bad` gets an unknown label?** Recommended:
+   **raise `ValueError`** — fail fast on user input (KISS rule), matching the
+   `summary_collector` unknown-family precedent, and safe because the load path
+   never calls `mark_as_bad`. The alternative (warn, keep recording) is gentler
+   for anyone who marks cells before the journal is populated, but it leaves
+   the same "nothing happened" ending that this issue is about.
+2. **Confirm the crash is really gone for the reporter.** The plan treats the
+   `KeyError` as fixed by #952 based on a local replay against `master`. Worth
+   asking the reporter to re-run on `master` (or the next release) before #950
+   is closed, in case their journal reaches the store through a path the replay
+   did not cover.
+3. **Scope check:** #949 (`b.plot` ignores `ir=True`) came from the same
+   session and the same notebook line as this traceback. Keep it a separate
+   issue — it is a plotting-argument bug, not a store/journal one.

cellpy-2.1.3.post3/.issueflows/03-solved-issues/issue950_status.md

@@ -0,0 +1,58 @@
+# Status: #950 `mark_as_bad` / `drop_cells_marked_bad` not working
+
+- [x] Done
+
+## What's done
+
+- Plan accepted 2026-08-29 (see [issue950_plan.md](issue950_plan.md)).
+- **Verified the reported crash is already fixed on `master`** by #952 and
+  merely unreleased (latest tag `v2.1.3.post1`; the reporter ran 2.1.3).
+  Replaying the issue's flow against `master` succeeds for a loaded store and
+  for a lazy loader store.
+- `Batch.mark_as_bad` raises `ValueError` for a label that is not in
+  `journal.cell_names`, naming the known cells.
+- `Batch.drop` warns (`UserWarning`) and no-ops for an unknown label instead of
+  silently doing nothing.
+- Regression test for #950's exact path: loaded batch → two `mark_as_bad` →
+  `drop_cells_marked_bad()` → `combine_summaries()` and the `b.experiment`
+  adapter (the `plot()` crash site). This path had **no** coverage before:
+  `test_drop_cells_marked_bad` used a journal-only batch with an empty store,
+  and `test_drop_loaded_cell_forgets_store_label` covers `drop`, not
+  `drop_cells_marked_bad`.
+- Tests for the unknown-label raise/warn and for the quiet-reload case.
+- Docs: `docs/getting_started/agents.md` drop recipe, root `AGENTS.md` batch
+  bullet, feedback contract in
+  [batch-load-orchestrator.md](../04-designs-and-guides/batch-load-orchestrator.md),
+  two rows in [test-registry.md](../04-designs-and-guides/test-registry.md).
+- `MPLBACKEND=Agg uv run pytest -m essential`: 781 passed, 58 skipped.
+
+## Deviation from the plan
+
+The plan had `drop_cells_marked_bad()` warn about `bad_cells` entries it could
+not drop. **Dropped** during implementation after checking the round-trip:
+`write_journal` persists `session`, so a cell dropped in one session is still
+listed in `bad_cells` after `save()` + reload, and `_finalize` calls
+`drop_cells_marked_bad()` on **every** `batch.load`. That warning would have
+fired on a completely normal round-trip (verified: reloaded journal has
+`bad_cells == ["gone"]` with `gone` absent from pages). Rejecting unknown
+labels in `mark_as_bad` closes the hole at the source instead, so the drop path
+stays quiet. `test_drop_cells_marked_bad_is_quiet_about_already_dropped_cells`
+pins this.
+
+- `MPLBACKEND=Agg uv run pytest` (full suite, `--extra batch`): 1737 passed,
+  17 skipped, 15 xfailed, 1 xpassed.
+- `HISTORY.md` bullet under `## [Unreleased]`.
+
+## Remaining work
+
+- None. The reporter is worth asking to re-confirm on the next release, since
+  their crash was fixed by #952 rather than by this PR.
+
+## Notes
+
+- `session["bad_cells"]` is deliberately not pruned on a successful drop — it
+  is the record a later `load(drop_bad_cells=True)` replays.
+- The environment needed `unixodbc` (`libodbc.so.2`) installed before
+  `pytest -m essential` could even collect `test_arbin_variants_two_stage.py`.
+  GitHub runners ship it; this cloud VM did not. Unrelated to this issue, but
+  it is the same class of problem as open issue #938.

cellpy-2.1.3.post3/.issueflows/03-solved-issues/issue967_original.md

@@ -0,0 +1,7 @@
+# Issue #967: Zensical docs contain strange markers
+
+Source: https://github.com/jepegit/cellpy/issues/967
+
+## Original issue text
+
+The built docs shows ":class:" etc while it most likely should render to something nicer. ![image](https://github.com/user-attachments/assets/8cd80c7a-5fad-4478-b23a-439ed278c6ff)