heinzel-issues 0.2.0__tar.gz

heinzel_issues-0.2.0/.copier-answers.yml

@@ -0,0 +1,5 @@
+# Generated by Copier. Keep this file so the template can be updated.
+_commit: v0.9.26
+_src_path: gh:helmut-hoffer-von-ankershoffen/heinzel
+plugin_name: issues
+plugin_summary: Report a problem or request something, and see when it is worked on, done and released.

heinzel_issues-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.acceptance/
+.preview/
+dist/
+release-dist/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.coverage*
+*.egg-info/
+.ruff_cache/

heinzel_issues-0.2.0/AGENTS.md

@@ -0,0 +1,39 @@
+# heinzel-issues
+
+Read [README.md](README.md). Edit the feature in `src/heinzel_issues/` and its tests; use the public `heinzel`
+and `heinzel.kernel` API. One `@module.operation` supplies CLI, MCP and REST. Add a service or model when the
+feature needs it; neither is required for a small operation. Never import a plugin implementation or core internals.
+
+Run from this plugin's directory:
+```sh
+make setup
+make check-fast
+make check
+make build
+make acceptance
+make preview
+make lock # after changing dependencies
+make release # preview only
+```
+
+Keep all feature changes in this directory. Setup never initializes Git for a collection plugin. The owning
+Makefile works even when the parent repository builds something else. A parent that provides collection commands
+also accepts `NAME=heinzel-issues` from its root. Publication uses the parent's generic plugin release workflow;
+do not copy a nested `.github/` or edit a parent registry.
+
+
+Each pytest file declares exactly one level: `unit`, `integration` or `e2e`. Write a behavior test for a change.
+Run the fast loop while editing and the owning full/installed-wheel checks before release. These commands install
+a compatible core wheel; they never run the core suite. `CORE=<wheel>` explicitly selects a candidate SDK.
+
+The source operation in the starter shows the minimum abstraction. Use the contributions preset or
+[extension guide](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/PLUGINS.md) for views,
+priorities, Today widgets, notifications and shared contracts. Ordinary dependencies belong in this project's
+`pyproject.toml`; regenerate its own lock. Use conventional commits and review nontrivial changes.
+
+Publishing requires a merged commit, this plugin's version and configured GitHub/PyPI publishing. Local
+`release` only checks/builds and previews; `publish` dispatches the protected workflow. Never upload a different
+rebuild under an existing version. See the README's release steps.
+Private sources use private GitHub releases and the installing person's `gh` login. PyPI is public; do not publish
+private sources there. The [custom plugin guide](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/PLUGIN_AUTHORING.md)
+documents separate repositories, catalog discovery and both release paths.

heinzel_issues-0.2.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.2.0
+
+Everything works in the app now; no step needs a terminal.
+
+- Set up in the app: the Issues page asks for the folder with the Beads database, checks that it answers, and saves
+  it (`connect`). Nothing is saved when the check fails. The app and the daemon follow the saved settings at their
+  next use, without a restart.
+- Open a report to read what you sent, the files you sent with it and its history: Sent, Being worked on, Done,
+  Released in.
+- Send a screenshot or a text file with a report from the app (up to 2 MiB), with Heinzel 0.9.45 or newer; the
+  confirmation shows the file shortened. An older Heinzel offers text only.
+- More labels: `issues.beads.extra_labels` (the "More labels" field in the setup form) gives every new report further
+  labels, so a team's intake queue sees it.
+- Your reports only: Issues lists and shows only items with the Issues label that were sent under your login name,
+  and changes only items with the Issues label. `list` and `show` are private operations now, so they need your
+  sign-in on the network interfaces.
+- What you type can never be read by the tracker program as an option: every value goes as `--name=value`.
+- The form says under which login name and with which labels a report is stored, before you send.
+- The view opens no terminal any more: the `hz setup issues` and `hz issues submit` buttons are gone, and messages
+  the app shows name no command.
+
+## 0.1.1
+
+Relock for Heinzel Core 0.9.40 (its AI extra adds pyjwt) and refresh the gallery.
+
+## 0.1.0
+
+- First release: report a problem or request something from the app or `hz issues submit`, and see it as
+  Received, Being worked on or Done, with the release that shipped it.
+- A task-tracking contract (submit, list, get, changes) with a built-in Beads connector; other trackers plug in
+  through the `heinzel_issues.connectors` entry point.
+- A notice when a report is being worked on, is done, or is released; open reports on Today.
+- Send from the app: the view's form uses the typed-input `send` action (Heinzel 0.9.30+), confirmed before it
+  runs; an older Heinzel gets the terminal command instead.
+- Beads writes go through the methods of Heinzel's `Tracker` contract (core ADR 0141) with the sender as actor;
+  no capability adapter is registered, so other trackers stay bound. Requires Heinzel 0.9.31.
+- Opt-in only: in no standard set, and it says how to set it up until a reachable tracker is configured.
+- Structured `issues.submit.*` and `issues.watch.*` log events, never with the typed text.

heinzel_issues-0.2.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

heinzel_issues-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Plugin authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

heinzel_issues-0.2.0/Makefile

@@ -0,0 +1,19 @@
+.DEFAULT_GOAL := help
+TOOLING ?= heinzel-plugin-tools @ https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/releases/download/tools-v0.3.7/heinzel_plugin_tools-0.3.7-py3-none-any.whl\#sha256=ac959c164e3726f86311c86fa9d3b4a3cbc82a6b4f81fae8bf462ee8103bd359
+unexport TOOLING CORE TAG REGISTRY
+export HZ_PLUGIN_TOOLING := $(value TOOLING)
+export PLUGIN_CORE := $(value CORE)
+export PLUGIN_TAG := $(value TAG)
+export PLUGIN_REGISTRY := $(value REGISTRY)
+MAKEOVERRIDES =
+PLUGIN := uv run --quiet --no-project --with "$$HZ_PLUGIN_TOOLING" hz-plugin
+
+.PHONY: help setup fix check-fast check test lock preview build acceptance audit release preflight publish
+help:
+	@echo 'make setup; make check-fast; make check; make preview; make build; make acceptance'
+	@echo 'make lock refreshes this plugin dependency lock; CORE=<wheel> selects a candidate SDK.'
+	@echo 'make release previews; make publish dispatches the protected release workflow.'
+setup fix check-fast check test lock preview build acceptance audit release preflight:
+	@$(PLUGIN) $@
+publish:
+	@$(PLUGIN) publish

heinzel_issues-0.2.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: heinzel-issues
+Version: 0.2.0
+Summary: Report a problem or request something, and see when it is done and released; needs a Beads database you can write to.
+Project-URL: Source, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/tree/main/plugins/heinzel-issues
+Project-URL: Changelog, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/blob/main/plugins/heinzel-issues/CHANGELOG.md
+Project-URL: Issues, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: heinzel<0.10,>=0.9.31
+Description-Content-Type: text/markdown
+
+# Issues
+
+Report a problem or request something, then see where it stands: **Received**, **Being worked on** or **Done**, and
+once it ships, **Released in 0.9.27 on 7 Nov 2026**. You never see the tracker behind it: no statuses of its own,
+no ids, no pull requests, unless you ask for the details.
+
+It is not installed, bundled or recommended by default: it needs a Beads database you can write to (today the
+private management repository). Add it with `hz system plugin add issues --confirm`.
+Until a tracker is set up the Issues page shows **Issue tracking is not set up** with a short form, never an error.
+Everything after that happens in the app; no step needs a terminal.
+
+## Use it
+
+- **In the app:** open **Issues** in the sidebar. The list shows each report with its state as a word and a mark
+  (○ Received, ◐ Being worked on, ✓ Done), never colour alone. Type what happened or what you would like and
+  press **Send**; the app shows what it will send and asks first. With Heinzel 0.9.45 or newer you can add a
+  screenshot or a text file (PNG, JPEG or text, up to 2 MiB). Select a report to read what you sent and its history:
+  Sent, Being worked on, Done, Released in. Your open reports also appear on Today.
+- **In a terminal:**
+
+  ```sh
+  hz issues submit "The footer clock jumps by a pixel every minute"
+  hz issues submit "Here is what I saw" --attachment shot.png
+  hz issues list
+  ```
+
+  `hz issues list --json` adds the details for agents and experts: the tracker, its id and status, and each pull
+  request with its release. `hz issues show <id>` shows one.
+- **Notices:** every five minutes the daemon looks for changes and tells you when a report is being worked on, is
+  done, and when it is released. The first check after turning Issues on only remembers what is there.
+
+When nothing is set up, the app says **Issue tracking is not set up** and asks for the tracker folder;
+`hz issues list` says the same and names `hz setup issues`.
+
+<!-- screenshots:start -->
+## Screenshots
+
+<img src="docs/assets/screenshots/issues-page.png" alt="Three fictional reports: received, being worked on, and released in 0.9.27 — with a form to send another" width="960">
+
+Three fictional reports: received, being worked on, and released in 0.9.27 — with a form to send another
+
+<img src="docs/assets/screenshots/report-history.png" alt="A fictional report opened: what was sent, the file sent with it, and its history up to the release" width="960">
+
+A fictional report opened: what was sent, the file sent with it, and its history up to the release
+
+<img src="docs/assets/screenshots/today-open-reports.png" alt="Your open fictional reports and requests on Today, in dark mode; done ones leave the list" width="960">
+
+Your open fictional reports and requests on Today, in dark mode; done ones leave the list
+
+<details>
+<summary>Command line</summary>
+
+<img src="docs/assets/screenshots/cli-list.png" alt="The same fictional reports and their plain states through the real CLI" width="960">
+
+The same fictional reports and their plain states through the real CLI
+
+</details>
+
+[Open the screenshot gallery](docs/assets/screenshots/index.html).
+<!-- screenshots:end -->
+
+## Set it up
+
+In the app, open **Issues**, enter the folder that holds the Beads database and press **Set up issue tracking**.
+Issues checks that the database answers before it saves anything, and works at once, without a restart. Under
+**More options** you can name more labels for every new report (emptying the field clears them) and git clones
+whose tags are releases.
+
+In a terminal, `hz setup issues` asks the same. Or set it directly:
+
+```toml
+[issues]
+tracker = "beads"
+
+[issues.beads]
+path = "~/Code/team-board"   # the folder with the .beads database
+label = "heinzel-issues"      # what Issues gives each report, and the items it shows
+extra_labels = ["intake"]     # optional: more labels for every new report, e.g. the one your team's queue reads
+
+[[issues.releases]]
+path = "~/Code/harbor"        # a clone on this computer; read, never fetched
+names = ["core"]              # how notes name it: "core #12"
+ref = "origin/main"
+tags = "v*"
+```
+
+`hz system doctor` reports Issues as up while it is off, and as down with the reason when a chosen tracker does
+not answer.
+
+## How "Released in" is found
+
+Whoever works on a report notes the pull request in the tracker: `Fixed in #562`, `gh-562`, `plugins #38` or a
+pull request link. Issues finds the merge commit whose subject ends in `(#562)` on the configured branch, then the
+oldest release tag matching the pattern that contains it. A report with several pull requests is released when the
+last of them is. The clone is only read; keep it fetched as you normally do.
+
+## Trackers
+
+Beads is built in: Issues runs `bd ... --json` in the configured folder, on this computer, and never syncs,
+pushes or publishes. Other trackers (Linear, Jira, GitHub issues, cards in git) plug in behind the same contract,
+described in [docs/CONTRACT.md](docs/CONTRACT.md), without a change to Issues or to Heinzel's core.
+
+Issues writes to Beads through the methods of Heinzel's `Tracker` contract (core ADR 0141): each write runs
+`bd --actor`, and a claim is Beads' atomic `--claim`. It registers no `tracker` capability adapter, so installing it
+never unbinds or replaces the tracker other plugins (GitHub, Atlassian) use.
+
+## Privacy
+
+What you send stays in the tracker you chose. Each report is stored there with your login name on this computer and
+the labels that are set up; the form says both before you send. Issues shows and reads only the reports you sent
+under that login name: other work in the same database, and other people's reports, never appear, by list or by id.
+Reading and sending need your sign-in to the app; nothing is open on the network interfaces without it. Issues stores only what it has already told you, under Heinzel's
+state folder, readable by you only. Notices are local, like every Heinzel notice.
+
+## Develop
+
+From this directory: `make setup`, `make check-fast`, `make check`, `make build`, `make acceptance`. The
+integration tests create a temporary Beads database and need `bd` installed; they are skipped without it.

heinzel_issues-0.2.0/README.md

@@ -0,0 +1,118 @@
+# Issues
+
+Report a problem or request something, then see where it stands: **Received**, **Being worked on** or **Done**, and
+once it ships, **Released in 0.9.27 on 7 Nov 2026**. You never see the tracker behind it: no statuses of its own,
+no ids, no pull requests, unless you ask for the details.
+
+It is not installed, bundled or recommended by default: it needs a Beads database you can write to (today the
+private management repository). Add it with `hz system plugin add issues --confirm`.
+Until a tracker is set up the Issues page shows **Issue tracking is not set up** with a short form, never an error.
+Everything after that happens in the app; no step needs a terminal.
+
+## Use it
+
+- **In the app:** open **Issues** in the sidebar. The list shows each report with its state as a word and a mark
+  (○ Received, ◐ Being worked on, ✓ Done), never colour alone. Type what happened or what you would like and
+  press **Send**; the app shows what it will send and asks first. With Heinzel 0.9.45 or newer you can add a
+  screenshot or a text file (PNG, JPEG or text, up to 2 MiB). Select a report to read what you sent and its history:
+  Sent, Being worked on, Done, Released in. Your open reports also appear on Today.
+- **In a terminal:**
+
+  ```sh
+  hz issues submit "The footer clock jumps by a pixel every minute"
+  hz issues submit "Here is what I saw" --attachment shot.png
+  hz issues list
+  ```
+
+  `hz issues list --json` adds the details for agents and experts: the tracker, its id and status, and each pull
+  request with its release. `hz issues show <id>` shows one.
+- **Notices:** every five minutes the daemon looks for changes and tells you when a report is being worked on, is
+  done, and when it is released. The first check after turning Issues on only remembers what is there.
+
+When nothing is set up, the app says **Issue tracking is not set up** and asks for the tracker folder;
+`hz issues list` says the same and names `hz setup issues`.
+
+<!-- screenshots:start -->
+## Screenshots
+
+<img src="docs/assets/screenshots/issues-page.png" alt="Three fictional reports: received, being worked on, and released in 0.9.27 — with a form to send another" width="960">
+
+Three fictional reports: received, being worked on, and released in 0.9.27 — with a form to send another
+
+<img src="docs/assets/screenshots/report-history.png" alt="A fictional report opened: what was sent, the file sent with it, and its history up to the release" width="960">
+
+A fictional report opened: what was sent, the file sent with it, and its history up to the release
+
+<img src="docs/assets/screenshots/today-open-reports.png" alt="Your open fictional reports and requests on Today, in dark mode; done ones leave the list" width="960">
+
+Your open fictional reports and requests on Today, in dark mode; done ones leave the list
+
+<details>
+<summary>Command line</summary>
+
+<img src="docs/assets/screenshots/cli-list.png" alt="The same fictional reports and their plain states through the real CLI" width="960">
+
+The same fictional reports and their plain states through the real CLI
+
+</details>
+
+[Open the screenshot gallery](docs/assets/screenshots/index.html).
+<!-- screenshots:end -->
+
+## Set it up
+
+In the app, open **Issues**, enter the folder that holds the Beads database and press **Set up issue tracking**.
+Issues checks that the database answers before it saves anything, and works at once, without a restart. Under
+**More options** you can name more labels for every new report (emptying the field clears them) and git clones
+whose tags are releases.
+
+In a terminal, `hz setup issues` asks the same. Or set it directly:
+
+```toml
+[issues]
+tracker = "beads"
+
+[issues.beads]
+path = "~/Code/team-board"   # the folder with the .beads database
+label = "heinzel-issues"      # what Issues gives each report, and the items it shows
+extra_labels = ["intake"]     # optional: more labels for every new report, e.g. the one your team's queue reads
+
+[[issues.releases]]
+path = "~/Code/harbor"        # a clone on this computer; read, never fetched
+names = ["core"]              # how notes name it: "core #12"
+ref = "origin/main"
+tags = "v*"
+```
+
+`hz system doctor` reports Issues as up while it is off, and as down with the reason when a chosen tracker does
+not answer.
+
+## How "Released in" is found
+
+Whoever works on a report notes the pull request in the tracker: `Fixed in #562`, `gh-562`, `plugins #38` or a
+pull request link. Issues finds the merge commit whose subject ends in `(#562)` on the configured branch, then the
+oldest release tag matching the pattern that contains it. A report with several pull requests is released when the
+last of them is. The clone is only read; keep it fetched as you normally do.
+
+## Trackers
+
+Beads is built in: Issues runs `bd ... --json` in the configured folder, on this computer, and never syncs,
+pushes or publishes. Other trackers (Linear, Jira, GitHub issues, cards in git) plug in behind the same contract,
+described in [docs/CONTRACT.md](docs/CONTRACT.md), without a change to Issues or to Heinzel's core.
+
+Issues writes to Beads through the methods of Heinzel's `Tracker` contract (core ADR 0141): each write runs
+`bd --actor`, and a claim is Beads' atomic `--claim`. It registers no `tracker` capability adapter, so installing it
+never unbinds or replaces the tracker other plugins (GitHub, Atlassian) use.
+
+## Privacy
+
+What you send stays in the tracker you chose. Each report is stored there with your login name on this computer and
+the labels that are set up; the form says both before you send. Issues shows and reads only the reports you sent
+under that login name: other work in the same database, and other people's reports, never appear, by list or by id.
+Reading and sending need your sign-in to the app; nothing is open on the network interfaces without it. Issues stores only what it has already told you, under Heinzel's
+state folder, readable by you only. Notices are local, like every Heinzel notice.
+
+## Develop
+
+From this directory: `make setup`, `make check-fast`, `make check`, `make build`, `make acceptance`. The
+integration tests create a temporary Beads database and need `bd` installed; they are skipped without it.

heinzel_issues-0.2.0/docs/CONTRACT.md

@@ -0,0 +1,51 @@
+# The task-tracking contract
+
+Issues talks to a tracker only through `TaskTracker` in `heinzel_issues._contract`. A connector implements four
+operations and maps the tracker's own statuses onto three states; everything else stays inside the connector.
+
+| Operation | What it does |
+|---|---|
+| `submit(title, body, attachments)` | Create an item from a person's report; it starts as `received`. |
+| `list()` | Every item submitted through Issues, newest first. |
+| `get(task_id)` | One item by the tracker's id. |
+| `changes(since)` | Items changed after `since` (all for `None`); the daemon's watch calls it every five minutes. |
+
+Each returns `Task`s: `id`, `title`, `body`, `state` (`received`, `working`, `done`), the tracker's own `status`,
+`created_at`, `updated_at`, `closed_at`, and `references`: text written by whoever works on the item (notes, links,
+close reason) where pull request numbers are found. Never put the submitter's own text in `references`.
+Optional: `started_at`, when someone started on it, and `attachments`, the names of the files sent with it; the
+opened report shows both, in its history and under what was sent.
+
+A connector raises `TrackerError` with a plain sentence that says what to do; Issues shows it as it is.
+
+## Adding a connector
+
+Register a factory in your package under the `heinzel_issues.connectors` entry point group:
+
+```toml
+[project.entry-points."heinzel_issues.connectors"]
+linear = "harbor_linear.issues:connect"
+```
+
+The factory receives the settings table `issues.connectors.<name>` and returns a `TaskTracker`. People choose it
+with `issues.tracker = "linear"`. A connector that fails to load is skipped; a built-in name always wins.
+
+## The Beads connector
+
+| Beads status | State |
+|---|---|
+| `open`, `deferred`, `pinned`, any custom status | Received |
+| `in_progress`, `blocked`, `hooked` | Being worked on |
+| `closed` | Done |
+
+It runs `bd create|list|show|update --json` in `issues.beads.path` with `BD_NON_INTERACTIVE=1`, labels every
+report with `issues.beads.label`, lists only items with that label, and copies attachments to
+`.beads/attachments/<id>/` next to the database, noting their path on the item.
+
+## Heinzel's Tracker contract
+
+`BeadsBoard` implements core's `Tracker` protocol (ADR 0141) over the same database: `issues_updated`, `create`,
+`claim`, `transition`, `note`, `attach` and `close`. A project is a Beads label. Every write runs
+`bd ... --actor <actor>`; `claim` is Beads' atomic `--claim` and refuses an item another actor holds. `hz issues
+submit` writes through it; listing and the watch read through the connector above. Issues registers no capability
+adapter, so it never changes which tracker other plugins are bound to.

heinzel_issues-0.2.0/docs/SCREENSHOTS.md

@@ -0,0 +1,10 @@
+# Screenshot gallery
+
+From the collection root, run `make screenshots NAME=heinzel-issues OPEN=1`.
+Review the [contact sheet](assets/screenshots/index.html) before committing.
+The [scene plan](screenshots.toml) describes the real UI and CLI captures.
+`make screenshots-check NAME=heinzel-issues` verifies freshness offline.
+
+Captures use a temporary fictional profile without connected accounts and an in-memory tracker with three
+fictional reports (`screenshot_fixture.py`); no Beads database is read or written.
+See the [author guide](../../../docs/SCREENSHOT_AUTHORING.md) for human and agent commands.

heinzel_issues-0.2.0/docs/SCREENSHOT_STORY.md

@@ -0,0 +1,44 @@
+## Audience
+People who use Heinzel and want to report a problem or request something without leaving the app, then follow it to the release that shipped it. Maintainers also need to know that the built-in tracker is a Beads database on this computer that they can write to; the plugin is optional and off until a tracker is set up (`README.md`, `[tool.heinzel.catalog]` in `pyproject.toml`).
+
+## Outcome
+The tracker is usable from within the app, with no terminal step: set it up, send a report, read the list with plain states, open one report for what was sent and its history, and see open reports on Today. The gallery shows the real plugin view and Core's Today with fictional data only. It must not claim that anything was sent: the demonstration tracker refuses sending.
+
+## The UI flows in the source
+All of this is one view, `src/heinzel_issues/views/index.js`, at the route `/?panel=issues:requests` (`ROUTE` in `_service.py`), reached from the sidebar entry Issues (`module.nav`, `module.action`, `module.view(name="requests", source="list")` in `__init__.py`).
+
+1. **Setup form.** While `data.ready` is false the view renders the form "Set up issue tracking": the status line "Issue tracking is not set up." (or the tracker's own problem text), the required field "Tracker folder", and under "More options" the fields "More labels" and "Release clones". The button "Set up issue tracking" runs the view action `connect` (operation `connect`), which checks that the folder holds a Beads database and that it answers before anything is saved, then works without a restart. The form says "Checking the folder…", then "Issue tracking is set up." or the reason nothing was saved.
+2. **Submit with confirm.** When ready, the composer "Report or request" has a text area ("What happened, or what would you like?"), an optional chooser "Screenshot or file (optional)" for a PNG, JPEG or text file up to 2 MiB, a line that says how it is stored ("Sent to the tracker under your login name …, with the labels …"), and the button Send. Send runs the view action `send` (operation `submit`, declared `read_only=False`, `private=True`). Core shows the call and asks before it runs; that confirmation is Core-rendered, not plugin UI. Cancelling keeps the typed text ("Not sent; your text is still here."); success says "Received. You will see here when someone is on it." The chooser appears only when Core reports the SDK feature `form-long-values`.
+3. **List with states.** The list "Your reports and requests" has one row per report: its title, and its state as a mark and a word, never colour alone: ○ Received, ◐ Being worked on, ✓ Done, or ✓ Released in 0.9.27 on 7 Nov 2026 once a release is found. An empty tracker shows "Nothing reported yet."
+4. **Detail and history.** A row is a button; selecting it expands the text sent after the title, "Sent with:" and the attachment names, and the ordered list "History": Sent, Being worked on, Done, Released in, each with its day.
+5. **Today cards.** `@module.widget(source="list")` puts a list card "Your reports and requests" on Core's Today at `/` with up to eight reports that are not done, each with its state and a link to the Issues page. It is absent while tracking is off or everything is done.
+
+Beyond the app: the CLI commands `hz issues list`, `submit`, `show` and `connect`, the prompted `hz setup issues`, a Doctor check `tracker`, and a five-minute job that emits Core notices on a state change or release. These are Core or terminal surfaces, not further plugin pages. No external provider UI is declared; Beads is reached through a local command and releases through local git clones.
+
+## Scenes
+1. **issues-page (UI, light):** flows 2 and 3 at rest. Three fictional reports, one per state, the done one as "Released in 0.9.27 on 7 Nov 2026", above the composer with its storage line and Send. The caption's "a form to send another" is accurate for the form being present; it is not a sent report.
+2. **report-history (UI, light):** flow 4. The fictional weather report is opened: its text, "Sent with: today-rain.png", and the history Sent 4 Nov 2026, Being worked on 4 Nov 2026, Done 5 Nov 2026, Released in 0.9.27 7 Nov 2026. A meaningful expanded state of the same real view.
+3. **today-open-reports (UI, dark):** flow 5. Core's Today with the two open fictional reports; the released one is absent.
+4. **cli-list (CLI):** `hz issues list` as a table with the columns Report or request, Status and Sent, for the same three reports. A real CLI result, not a substitute for the UI.
+
+What the plan does not capture: the setup form (flow 1) and Core's confirmation or a successful send (the rest of flow 2). The fixture forces a ready tracker and its `submit` raises "Sending is off in this demonstration.", so neither can be shown by this plan and no caption may imply them. Showing them needs further scenes with a fixture state that is not set up and a plan step that presses Send; that is a change to the plan and needs a new definition.
+
+## Fictional fixtures
+`docs/screenshot_fixture.py` replaces the built-in tracker with one in memory holding three fictional tasks (demo-1 to demo-3), one fictional attachment name with no file behind it, and a temporary local git clone with empty commits and the tags v0.9.26 and v0.9.27, so that "Fixed in #7" resolves to 0.9.27 on 7 Nov 2026. It sets the tracker and the release clone through environment settings and then runs the real app. No Beads database is read or written and nothing is sent anywhere. Browser time is fixed at 8 Nov 2026.
+
+## Privacy pitfalls
+- The composer prints the login name of whoever runs the capture (`reporter()` in `_beads.py` reads the operating system's login name) together with the label `heinzel-issues`. The image is acceptable only if that name is the capture profile's fictional one; a real login name on scenes 1 or 2 is a rejection.
+- The release clone lives in a temporary folder whose path is in the settings. It must not appear in any image or transcript; the list and the table do not print it, the JSON output would.
+- The setup form's "Tracker folder" is prefilled from settings and would show a real path if it were ever captured from a real profile.
+- Report titles, body and the attachment name must be exactly the fixture's; any text from a real tracker, a real bead id or a pull request of a real repository is a rejection. The view and the table do not print tracker ids.
+- Core chrome around the view (sidebar, account name, version, Doctor card, footer, notices, chat) comes from the capture profile; check it for real names, host names, paths, e-mail addresses and tokens. The toolkit's own presentation mapping is limited to the owning interpreter path shown as `/demo-profile/.venv` and the Doctor hostname shown as `demo-host`; neither is a privacy acceptance.
+
+## Acceptance criteria
+- Four distinct captures from the real app and CLI through the fixture; no forged HTML, duplicates or caption-only variants. Scenes 1 and 2 are genuine feature UI states, scene 3 is a Core feature surface fed by the plugin, scene 4 is identified as CLI.
+- Scene 1 shows all three rows with mark and word, and the composer; scene 2 shows the body text, "Sent with: today-rain.png" and all four history steps with dates; scene 3 shows exactly the two open reports in an applied dark appearance; scene 4 lists the same three with the same states.
+- Light and dark are actually applied. Text is readable, nothing clipped, the state marks are visible.
+- Do not describe the file chooser as shown unless it is in the image; it depends on the captured Core.
+- Captions say the data is fictional and claim nothing about setup, confirmation or a successful send.
+- An independent reviewer opens every image and reads every transcript for privacy and accuracy before publication.
+
+This analysis read the staged source, README, plan and fixture; it ran no plugin code and captured nothing.

heinzel_issues-0.2.0/docs/assets/screenshots/capture.json

@@ -0,0 +1,84 @@
+{
+  "format": 1,
+  "plugin": "heinzel-issues",
+  "core_version": "0.9.42",
+  "inputs_sha256": "df95a9d4a53cb16aa0a3572bc04b88332dfbb102fdf4ff439bb1d309ecf099a2",
+  "images": {
+    "docs/assets/screenshots/issues-page.png": "4172860cdbf81d5b9b907a47a73641889cefcd3bcc185b43bd9d46815c09f126",
+    "docs/assets/screenshots/report-history.png": "7605e12edddcf1dc7524c801850c6138605b430853a3aa81ff46064b8cde0691",
+    "docs/assets/screenshots/today-open-reports.png": "f7e36260487c7a30574122f5a6705732edee045cd720d0b7717fc4b307ead56e",
+    "docs/assets/screenshots/cli-list.png": "e8a2c412a35760cf9eb4725826c6b6ac075d532ddc910392a48e23af56b563bc"
+  },
+  "review_bundle": {
+    "format": 2,
+    "source_story": {
+      "path": "source-story.md",
+      "sha256": "baac94e327f1dbec7633b9b7e4b9de5fb398f2d57c1d8f8a3ce68984bc511401"
+    },
+    "definition": {
+      "format": 1,
+      "reviewer": "fable-issues-story",
+      "source_sha256": "f69054b3ab966d5ca2aea6e080b3ebfd43c5d210379e3f8005829ce6da54860c",
+      "plan_sha256": "e7395659d00a341e8c5fcf62a26cc2765e7812e405390baa9fe1ae815fab2710",
+      "story_sha256": "baac94e327f1dbec7633b9b7e4b9de5fb398f2d57c1d8f8a3ce68984bc511401"
+    },
+    "plugin": "heinzel-issues",
+    "core_version": "0.9.42",
+    "inputs_sha256": "df95a9d4a53cb16aa0a3572bc04b88332dfbb102fdf4ff439bb1d309ecf099a2",
+    "screenshots": [
+      {
+        "path": "docs/assets/screenshots/issues-page.png",
+        "surface": "ui",
+        "caption": "Three fictional reports: received, being worked on, and released in 0.9.27 \u2014 with a form to send another"
+      },
+      {
+        "path": "docs/assets/screenshots/report-history.png",
+        "surface": "ui",
+        "caption": "A fictional report opened: what was sent, the file sent with it, and its history up to the release"
+      },
+      {
+        "path": "docs/assets/screenshots/today-open-reports.png",
+        "surface": "ui",
+        "caption": "Your open fictional reports and requests on Today, in dark mode; done ones leave the list"
+      },
+      {
+        "path": "docs/assets/screenshots/cli-list.png",
+        "surface": "cli",
+        "caption": "The same fictional reports and their plain states through the real CLI"
+      }
+    ],
+    "images": {
+      "issues-page.png": "4172860cdbf81d5b9b907a47a73641889cefcd3bcc185b43bd9d46815c09f126",
+      "report-history.png": "7605e12edddcf1dc7524c801850c6138605b430853a3aa81ff46064b8cde0691",
+      "today-open-reports.png": "f7e36260487c7a30574122f5a6705732edee045cd720d0b7717fc4b307ead56e",
+      "cli-list.png": "e8a2c412a35760cf9eb4725826c6b6ac075d532ddc910392a48e23af56b563bc"
+    },
+    "transcripts": {
+      "issues-page.txt": "4e32e4e6bbcd79d9c69b679b75de3a51130bc0e01a66473d1c26e2ebc32d2cca",
+      "report-history.txt": "8464fe38ca16fca424081cc011998033d16ffe8b3494dd40f9d2c3311f02ea15",
+      "today-open-reports.txt": "530b3b464fd7c0d108890cb6c4b44a076913134d933868e6c93aadb66e4144e0",
+      "cli-list.txt": "d0eac2c0b1b435cac45b7f7052b732fe1e8f619035e7778e11b8f6e6101ff08f"
+    },
+    "bundle_sha256": "89e1f1751c8683837e61b7ee48b26b60e15ed4991e2de7fab1dbc096281a2668"
+  },
+  "privacy_review": {
+    "format": 1,
+    "bundle_sha256": "89e1f1751c8683837e61b7ee48b26b60e15ed4991e2de7fab1dbc096281a2668",
+    "reviewer": "fable-issues-story",
+    "decision": "approve",
+    "checked_images": [
+      "issues-page.png",
+      "report-history.png",
+      "today-open-reports.png",
+      "cli-list.png"
+    ],
+    "checks": {
+      "tokens_absent": true,
+      "personal_data_absent": true,
+      "feature_relevant": true,
+      "multiple_ui_scenes": true,
+      "captions_accurate": true
+    },
+    "findings": []
+  }
+}

heinzel_issues-0.2.0/docs/assets/screenshots/cli-list.txt

@@ -0,0 +1,7 @@
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
+┃ Report or request                              ┃ Status                           ┃ Sent        ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
+│ Add a dark theme to the printed agenda         │ Received                         │ 08 Nov 2026 │
+│ The footer clock jumps by a pixel every minute │ Being worked on                  │ 06 Nov 2026 │
+│ Weather shows yesterday's rain after waking up │ Released in 0.9.27 on 7 Nov 2026 │ 04 Nov 2026 │
+└────────────────────────────────────────────────┴──────────────────────────────────┴─────────────┘

heinzel_issues-0.2.0/docs/assets/screenshots/index.html

@@ -0,0 +1 @@
+<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>heinzel-issues screenshots</title><style>body{font:16px/1.6 system-ui;margin:2rem;background:#faf8f3;color:#263b32}main{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,420px),1fr));gap:1rem}figure{margin:0;padding:1rem;background:white;border:1px solid #d8ddd3;border-radius:12px}img{width:100%;height:auto}figcaption{margin-top:.75rem}a:focus-visible{outline:3px solid #a64028}</style><h1>heinzel-issues</h1><p>Isolated demonstration profile · Core 0.9.42 · Review these captures before committing. Click an image to inspect it at full size.</p><main><figure><a href="issues-page.png"><img src="issues-page.png" alt="Three fictional reports: received, being worked on, and released in 0.9.27 — with a form to send another"></a><figcaption>UI · Three fictional reports: received, being worked on, and released in 0.9.27 — with a form to send another</figcaption></figure><figure><a href="report-history.png"><img src="report-history.png" alt="A fictional report opened: what was sent, the file sent with it, and its history up to the release"></a><figcaption>UI · A fictional report opened: what was sent, the file sent with it, and its history up to the release</figcaption></figure><figure><a href="today-open-reports.png"><img src="today-open-reports.png" alt="Your open fictional reports and requests on Today, in dark mode; done ones leave the list"></a><figcaption>UI · Your open fictional reports and requests on Today, in dark mode; done ones leave the list</figcaption></figure><figure><a href="cli-list.png"><img src="cli-list.png" alt="The same fictional reports and their plain states through the real CLI"></a><figcaption>CLI · The same fictional reports and their plain states through the real CLI</figcaption></figure></main></html>