bugcap 0.2.2__tar.gz → 0.3.0__tar.gz

{bugcap-0.2.2/src/bugcap.egg-info → bugcap-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bugcap
-Version: 0.2.2
+Version: 0.3.0
 Summary: Local-first, agent-readable bug capture: annotated screenshots + notes, stored locally, synced to trackers on your own schedule.
 Author: Konrad Tagnon Amen ALAHASSA
 License: MIT
@@ -68,8 +68,8 @@ bugcap keeps the whole loop in one place:
 ## Quick start
 
 ```bash
-# install (from GitHub until the PyPI release is live)
-pipx install 'bugcap[mcp] @ git+https://github.com/amenalahassa/bugcap'
+# install from PyPI
+pipx install 'bugcap[mcp]'
 
 bugcap setup --yes                      # detects or installs a capture tool
 cd ~/code/myproject && bugcap init      # scope reports to this repo
@@ -128,8 +128,8 @@ Requires Python 3.10 or newer. The core CLI uses only the standard library (plus
 Python 3.11). The MCP server is an optional extra.
 
 ```bash
-pipx install 'bugcap[mcp] @ git+https://github.com/amenalahassa/bugcap'   # recommended
-uv tool install 'bugcap[mcp] @ git+https://github.com/amenalahassa/bugcap'
+pipx install 'bugcap[mcp]'   # recommended
+uv tool install 'bugcap[mcp]'
 pip install -e '.[dev,mcp]'                                             # development
 ```
 
@@ -146,7 +146,7 @@ pull and sync, MCP, and where data lives per OS.
 
 Notes on the more involved behaviour:
 
-- **`@` references.** `@1` or `@login-error` in a note points at an image. They are validated on save, and relabelling or removing a referenced image needs `--force`.
+- **References.** In a note, `@i1` is image 1, `@v2` a video, `@g3` an animated GIF, `@f4` a frame set, and `@login-error` a labelled item. `#3` points at report 3 (a missing one is kept as text with a warning). Media references are validated on save, and relabelling or removing a referenced item needs `--force`.
 - **Repo values** (`init`, `sync`, `config repo set`) are checked for format and, with `gh`, for existence. Changing the repo identity offers to move existing reports.
 - **Media sync** over `[sync] max_upload_mb` (default 25) is skipped with a warning.
 

{bugcap-0.2.2 → bugcap-0.3.0}/README.md

@@ -52,8 +52,8 @@ bugcap keeps the whole loop in one place:
 ## Quick start
 
 ```bash
-# install (from GitHub until the PyPI release is live)
-pipx install 'bugcap[mcp] @ git+https://github.com/amenalahassa/bugcap'
+# install from PyPI
+pipx install 'bugcap[mcp]'
 
 bugcap setup --yes                      # detects or installs a capture tool
 cd ~/code/myproject && bugcap init      # scope reports to this repo
@@ -112,8 +112,8 @@ Requires Python 3.10 or newer. The core CLI uses only the standard library (plus
 Python 3.11). The MCP server is an optional extra.
 
 ```bash
-pipx install 'bugcap[mcp] @ git+https://github.com/amenalahassa/bugcap'   # recommended
-uv tool install 'bugcap[mcp] @ git+https://github.com/amenalahassa/bugcap'
+pipx install 'bugcap[mcp]'   # recommended
+uv tool install 'bugcap[mcp]'
 pip install -e '.[dev,mcp]'                                             # development
 ```
 
@@ -130,7 +130,7 @@ pull and sync, MCP, and where data lives per OS.
 
 Notes on the more involved behaviour:
 
-- **`@` references.** `@1` or `@login-error` in a note points at an image. They are validated on save, and relabelling or removing a referenced image needs `--force`.
+- **References.** In a note, `@i1` is image 1, `@v2` a video, `@g3` an animated GIF, `@f4` a frame set, and `@login-error` a labelled item. `#3` points at report 3 (a missing one is kept as text with a warning). Media references are validated on save, and relabelling or removing a referenced item needs `--force`.
 - **Repo values** (`init`, `sync`, `config repo set`) are checked for format and, with `gh`, for existence. Changing the repo identity offers to move existing reports.
 - **Media sync** over `[sync] max_upload_mb` (default 25) is skipped with a warning.
 

{bugcap-0.2.2 → bugcap-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bugcap"
-version = "0.2.2"
+version = "0.3.0"
 description = "Local-first, agent-readable bug capture: annotated screenshots + notes, stored locally, synced to trackers on your own schedule."
 readme = "README.md"
 requires-python = ">=3.10"

bugcap-0.3.0/src/bugcap/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

{bugcap-0.2.2 → bugcap-0.3.0}/src/bugcap/agent_api.py

@@ -120,7 +120,8 @@ def update_notes(store: Store, id: int, notes: str) -> dict:
     except ServiceError as exc:
         return {"error": exc.message, **exc.as_dict()}
     view = service.get_report_view(store, id)
-    return {"report_id": report.id, "notes": report.notes, "references": view.references}
+    warnings = service.report_ref_warnings(store, report.notes)
+    return {"report_id": report.id, "notes": report.notes, "references": view.references, "warnings": warnings}
 
 
 def _resolve_slug(explicit: Optional[str]) -> Optional[str]:

{bugcap-0.2.2 → bugcap-0.3.0}/src/bugcap/cli.py

@@ -42,17 +42,26 @@ def print_ingest(added, rejected) -> None:
     """One line per input: `added #<idx> ...` on stdout, `skipped ...` on stderr."""
     for media in added:
         name = os.path.basename(media.path or "")
-        print(f"added #{media.idx} {name} ({media.kind}, {human_size(media.size_bytes)})")
+        print(f"added {refs.media_token(media)} {name} ({media.kind}, {human_size(media.size_bytes)})")
     for item in rejected:
         print(f"skipped {item['source']}: {item['reason']}", file=sys.stderr)
 
 
 # --- capture / list / show ----------------------------------------------------
 
+def _warn_report_refs(store: Store, notes) -> None:
+    """Soft warnings for `#N` references to reports that do not exist (never a failure)."""
+    for line in service.report_ref_warnings(store, notes or ""):
+        print(line, file=sys.stderr)
+
+
 def cmd_capture(args: argparse.Namespace) -> int:
     cfg = current_repo()
     captured: Optional[str] = None
-    if not args.image:
+    if args.no_image and (args.image or args.label):
+        print("error: --no-image cannot be combined with --image or --label", file=sys.stderr)
+        return 2
+    if not args.image and not args.no_image:
         try:
             captured = str(capture.capture_screenshot())
         except CaptureError as exc:
@@ -89,6 +98,8 @@ def cmd_capture(args: argparse.Namespace) -> int:
         except ServiceError as exc:
             print_service_error(exc)
             return 1
+        if report is not None:
+            _warn_report_refs(store, report.notes)
 
     if report is None:
         print_ingest([], result.rejected)
@@ -103,6 +114,27 @@ def cmd_capture(args: argparse.Namespace) -> int:
     return 1 if result.rejected else 0
 
 
+def cmd_delete(args: argparse.Namespace) -> int:
+    with Store() as store:
+        report = resolve_report(store, args.id)
+        if report is None:
+            return 1
+        if not args.yes:
+            if sys.stdin is None or not sys.stdin.isatty():
+                print("error: refusing to delete without confirmation; re-run with --yes", file=sys.stderr)
+                return 2
+            answer = input(
+                f"Delete report #{report.id} {report.title!r} and its {len(report.media)} image(s)? [y/N] "
+            ).strip().lower()
+            if answer != "y":
+                print("Nothing deleted.")
+                return 1
+        service.delete_report(store, args.id)
+
+    print(f"Deleted report #{report.id}: {report.title}")
+    return 0
+
+
 def cmd_list(args: argparse.Namespace) -> int:
     cfg = current_repo()
     scope = cfg.key if (cfg is not None and not args.all) else None
@@ -142,7 +174,7 @@ def cmd_show(args: argparse.Namespace) -> int:
         for m in detailed:
             where = m.path or f"({len(m.frames)} frames)"
             origin = f"  (source: {m.source})" if m.source else ""
-            print(f"    #{m.idx}  {m.kind:8s} {m.label or '-':12s} {where}  {human_size(m.size_bytes)}{origin}")
+            print(f"    {refs.media_token(m)}  {m.kind:8s} {m.label or '-':12s} {where}  {human_size(m.size_bytes)}{origin}")
     print(f"  synced_refs:")
     if report.synced_refs:
         for tracker, ref in report.synced_refs.items():
@@ -440,6 +472,8 @@ def cmd_edit(args: argparse.Namespace) -> int:
             print(f"error: {exc}", file=sys.stderr)
             return 2
 
+        _warn_report_refs(store, report.notes)
+
     changed = []
     if args.title is not None:
         changed.append("title")
@@ -529,6 +563,7 @@ def cmd_attach(args: argparse.Namespace) -> int:
                 print("warning: the image was attached but the note was not saved.", file=sys.stderr)
                 return 1
         current = store.get(args.id)
+        _warn_report_refs(store, current.notes)
         if args.image:
             try:
                 refs.validate_references(current.notes, current.media)
@@ -552,7 +587,7 @@ def cmd_images(args: argparse.Namespace) -> int:
         if args.action is None:
             for m in report.media:
                 where = m.path or f"({len(m.frames)} frames)"
-                print(f"#{m.idx}  {m.label or '-':12s} {m.kind:8s} {human_size(m.size_bytes):>9s}  {where}")
+                print(f"{refs.media_token(m)}  {m.label or '-':12s} {m.kind:8s} {human_size(m.size_bytes):>9s}  {where}")
             return 0
         try:
             if args.action == "relabel":
@@ -634,8 +669,9 @@ def cmd_record(args: argparse.Namespace) -> int:
             recorder.discard(result)
             print_service_error(exc)
             return 1
+        _warn_report_refs(store, report.notes)
     print(f"recorded {result.duration:.1f} s, {human_size(result.size_bytes)} ({result.kind}), stopped: {result.reason}")
-    print(f"added #{media.idx} to report #{report.id}")
+    print(f"added {refs.media_token(media)} to report #{report.id}")
     return 0
 
 
@@ -828,8 +864,15 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--image", action="append", metavar="SRC",
                    help="Import an image (path, glob or http(s) URL) instead of launching a capture tool; repeatable.")
     p.add_argument("--label", action="append", help="Label for the --image at the same position (repeatable).")
+    p.add_argument("--no-image", dest="no_image", action="store_true",
+                   help="Save a text-only report: no capture tool and no image.")
     p.set_defaults(func=cmd_capture)
 
+    p = sub.add_parser("delete", help="Permanently delete a report and its images (not synced GitHub issues).")
+    p.add_argument("id", type=int, help="Report id (see `bugcap list`).")
+    p.add_argument("--yes", action="store_true", help="Delete without the confirmation prompt.")
+    p.set_defaults(func=cmd_delete)
+
     p = sub.add_parser("list", help="List reports (current repo only, unless --all).")
     p.add_argument("--all", action="store_true", help="List reports from every repo.")
     p.set_defaults(func=cmd_list)

{bugcap-0.2.2 → bugcap-0.3.0}/src/bugcap/dashboard/api.py

@@ -101,5 +101,7 @@ def set_notes(store, report_id: int, body: dict) -> dict:
     notes = body.get("notes")
     if not isinstance(notes, str):
         raise ServiceError("bad_query", "body must be {\"notes\": \"...\"}")
-    service.set_notes(store, report_id, notes)
-    return get_report(store, report_id)
+    report = service.set_notes(store, report_id, notes)
+    view = get_report(store, report_id)
+    view["warnings"] = service.report_ref_warnings(store, report.notes)
+    return view

{bugcap-0.2.2 → bugcap-0.3.0}/src/bugcap/dashboard/static/app.js

@@ -94,7 +94,8 @@
       var i = document.createElement("img");
       i.src = m.url; i.alt = m.label || ("image " + m.index); fig.appendChild(i);
     }
-    var label = caption || ("#" + m.index);
+    var letters = {image: "i", video: "v", animated: "g", frames: "f"};
+    var label = caption || ("@" + (letters[m.kind] || "i") + m.index);
     if (m.label) label += " (" + m.label + ")";
     fig.appendChild(el("figcaption", label + " · " + m.kind + " · " + Math.round(m.size_bytes / 1024) + " KB"));
     return fig;

{bugcap-0.2.2 → bugcap-0.3.0}/src/bugcap/live.py

@@ -22,6 +22,10 @@ TK_HINT = (
 )
 NO_DESKTOP = "Live mode needs a desktop session (no DISPLAY or WAYLAND_DISPLAY is set)."
 THUMB = 420
+# Light palette; the control and details windows share it (see `_App.style`).
+BG, CARD, TEXT, MUTED = "#f4f5f7", "#ffffff", "#111827", "#6b7280"
+ACCENT, ACCENT_ACTIVE, BORDER = "#2563eb", "#1d4ed8", "#d1d5db"
+DANGER, WARNING = "#b91c1c", "#b45309"
 
 
 def check_environment() -> tuple[int, str]:
@@ -69,25 +73,67 @@ class _App:
         self.widgets: dict = {}
         self.pending_drafts: list = []
 
+    # --- styling ---------------------------------------------------------------
+
+    def style(self) -> None:
+        """One consistent look for every window: a flat light theme with an accent button."""
+        tk, ttk = self.tk, self.ttk
+        import tkinter.font as tkfont
+
+        base = tkfont.nametofont("TkDefaultFont")
+        self.body_font = base
+        self.title_font = base.copy()
+        self.title_font.configure(size=base.cget("size") + 4, weight="bold")
+        self.heading_font = base.copy()
+        self.heading_font.configure(weight="bold")
+        self.root.configure(background=BG)
+        style = ttk.Style(self.root)
+        if "clam" in style.theme_names():
+            style.theme_use("clam")
+        style.configure(".", background=BG, foreground=TEXT, font=base)
+        style.configure("TFrame", background=BG)
+        style.configure("Card.TFrame", background=CARD, bordercolor=BORDER, relief="solid", borderwidth=1)
+        style.configure("TLabel", background=BG, foreground=TEXT)
+        style.configure("Card.TLabel", background=CARD)
+        style.configure("Title.TLabel", font=self.title_font)
+        style.configure("Heading.TLabel", font=self.heading_font)
+        style.configure("Muted.TLabel", foreground=MUTED)
+        style.configure("Muted.Card.TLabel", background=CARD, foreground=MUTED)
+        style.configure("Error.TLabel", foreground=DANGER)
+        style.configure("Warning.TLabel", foreground=WARNING)
+        style.configure("TButton", padding=(14, 6), background=CARD, bordercolor=BORDER, lightcolor=CARD,
+                        darkcolor=CARD, focuscolor=CARD)
+        style.map("TButton", background=[("active", BG), ("disabled", BG)], foreground=[("disabled", MUTED)])
+        style.configure("Accent.TButton", padding=(18, 8), background=ACCENT, foreground="#ffffff",
+                        bordercolor=ACCENT, lightcolor=ACCENT, darkcolor=ACCENT, focuscolor=ACCENT)
+        style.map("Accent.TButton", background=[("active", ACCENT_ACTIVE), ("disabled", BORDER)],
+                  foreground=[("disabled", MUTED)])
+        style.configure("TEntry", fieldbackground=CARD, bordercolor=BORDER, lightcolor=BORDER,
+                        darkcolor=BORDER, padding=4)
+        style.map("TEntry", bordercolor=[("focus", ACCENT)], lightcolor=[("focus", ACCENT)])
+        style.configure("TCombobox", fieldbackground=CARD, bordercolor=BORDER, padding=3)
+
     # --- control window --------------------------------------------------------
 
     def start_ui(self) -> None:
         tk, ttk, root = self.tk, self.ttk, self.root
         root.title("bugcap live")
         root.resizable(False, False)
+        self.style()
         notice = ""
         try:
             root.attributes("-topmost", True)
         except tk.TclError:
             notice = "Always-on-top is not supported here; the window may be hidden by others."
-        frame = ttk.Frame(root, padding=12)
+        frame = ttk.Frame(root, padding=16)
         frame.grid()
-        self.start_button = ttk.Button(frame, text="Start", command=self.on_start)
-        self.start_button.grid(row=0, column=0, sticky="ew")
-        self.counter = ttk.Label(frame, text="0 saved this session")
-        self.counter.grid(row=1, column=0, pady=(8, 0))
-        self.status = ttk.Label(frame, text=notice, wraplength=240, foreground="#a15c00")
-        self.status.grid(row=2, column=0, pady=(4, 0))
+        ttk.Label(frame, text="bugcap live", style="Title.TLabel").grid(row=0, column=0, sticky="w")
+        self.start_button = ttk.Button(frame, text="Start capture", style="Accent.TButton", command=self.on_start)
+        self.start_button.grid(row=1, column=0, sticky="ew", pady=(12, 0))
+        self.counter = ttk.Label(frame, text="0 saved this session", style="Muted.TLabel")
+        self.counter.grid(row=2, column=0, pady=(10, 0))
+        self.status = ttk.Label(frame, text=notice, wraplength=260, style="Warning.TLabel")
+        self.status.grid(row=3, column=0, pady=(6, 0), sticky="w")
         root.protocol("WM_DELETE_WINDOW", self.on_close_control)
         self.pending_drafts = drafts.list_drafts(self.cfg.key if self.cfg else None)
         root.after(200, self.offer_drafts)
@@ -166,44 +212,56 @@ class _App:
             win.attributes("-topmost", True)
         except tk.TclError:
             pass
-        frame = ttk.Frame(win, padding=12)
+        self.style()
+        frame = ttk.Frame(win, padding=16)
         frame.grid()
         w = self.widgets = {}
+        ttk.Label(frame, text="New bug report", style="Title.TLabel").grid(row=0, column=0, columnspan=2, sticky="w")
 
+        preview = ttk.Frame(frame, style="Card.TFrame", padding=6)
+        preview.grid(row=1, column=0, columnspan=2, pady=(10, 12))
         try:
             image = tk.PhotoImage(file=str(self.session.screenshot))
             factor = max(1, -(-max(image.width(), image.height()) // THUMB))
             w["photo"] = image.subsample(factor, factor) if factor > 1 else image
-            ttk.Label(frame, image=w["photo"]).grid(row=0, column=0, columnspan=2, pady=(0, 8))
+            ttk.Label(preview, image=w["photo"], style="Card.TLabel").grid()
         except tk.TclError:
-            ttk.Label(frame, text="(preview unavailable)").grid(row=0, column=0, columnspan=2)
+            ttk.Label(preview, text="(preview unavailable)", style="Muted.Card.TLabel").grid()
 
         prefill = prefill or {}
-        ttk.Label(frame, text="Title").grid(row=1, column=0, sticky="w")
-        w["title"] = ttk.Entry(frame, width=48)
-        w["title"].grid(row=1, column=1, sticky="ew")
+        form = ttk.Frame(frame)
+        form.grid(row=2, column=0, columnspan=2, sticky="ew")
+        form.columnconfigure(1, weight=1)
+        ttk.Label(form, text="Title", style="Heading.TLabel").grid(row=0, column=0, sticky="nw", padx=(0, 12), pady=4)
+        w["title"] = ttk.Entry(form, width=48)
+        w["title"].grid(row=0, column=1, sticky="ew", pady=4)
         w["title"].insert(0, prefill.get("title", ""))
-        ttk.Label(frame, text="Notes").grid(row=2, column=0, sticky="nw")
-        w["notes"] = tk.Text(frame, width=48, height=6, wrap="word")
-        w["notes"].grid(row=2, column=1, sticky="ew")
+        ttk.Label(form, text="Notes", style="Heading.TLabel").grid(row=1, column=0, sticky="nw", padx=(0, 12), pady=4)
+        w["notes"] = tk.Text(
+            form, width=48, height=6, wrap="word", relief="flat", background=CARD, foreground=TEXT,
+            highlightthickness=1, highlightbackground=BORDER, highlightcolor=ACCENT, padx=6, pady=4,
+            font=self.body_font,
+        )
+        w["notes"].grid(row=1, column=1, sticky="ew", pady=4)
         w["notes"].insert("1.0", prefill.get("notes", ""))
         w["notes"].bind("<KeyRelease>", lambda e: self.check_notes())
-        ttk.Label(frame, text="Tags").grid(row=3, column=0, sticky="w")
-        w["tags"] = ttk.Entry(frame, width=48)
-        w["tags"].grid(row=3, column=1, sticky="ew")
+        ttk.Label(form, text="Tags", style="Heading.TLabel").grid(row=2, column=0, sticky="w", padx=(0, 12), pady=4)
+        w["tags"] = ttk.Entry(form, width=48)
+        w["tags"].grid(row=2, column=1, sticky="ew", pady=4)
         w["tags"].insert(0, ", ".join(initial_tags(self.cfg, prefill)))
-        ttk.Label(frame, text="Status").grid(row=4, column=0, sticky="w")
-        w["status"] = ttk.Combobox(frame, values=list(STATUSES), state="readonly", width=16)
+        ttk.Label(form, text="Status", style="Heading.TLabel").grid(row=3, column=0, sticky="w", padx=(0, 12), pady=4)
+        w["status"] = ttk.Combobox(form, values=list(STATUSES), state="readonly", width=16)
         w["status"].set(prefill.get("status", "open"))
-        w["status"].grid(row=4, column=1, sticky="w")
-        ttk.Label(frame, text="Repo").grid(row=5, column=0, sticky="w")
-        ttk.Label(frame, text=(self.cfg.key if self.cfg else "(none)")).grid(row=5, column=1, sticky="w")
-        w["error"] = ttk.Label(frame, text="", foreground="#b00020", wraplength=420)
-        w["error"].grid(row=6, column=0, columnspan=2, sticky="w", pady=(6, 0))
+        w["status"].grid(row=3, column=1, sticky="w", pady=4)
+        ttk.Label(form, text="Repo", style="Heading.TLabel").grid(row=4, column=0, sticky="w", padx=(0, 12), pady=4)
+        ttk.Label(form, text=(self.cfg.key if self.cfg else "(none)"), style="Muted.TLabel").grid(
+            row=4, column=1, sticky="w", pady=4)
+        w["error"] = ttk.Label(frame, text="", style="Error.TLabel", wraplength=420)
+        w["error"].grid(row=3, column=0, columnspan=2, sticky="w", pady=(6, 0))
         buttons = ttk.Frame(frame)
-        buttons.grid(row=7, column=0, columnspan=2, sticky="e", pady=(8, 0))
-        ttk.Button(buttons, text="Discard", command=self.on_discard).grid(row=0, column=0, padx=4)
-        ttk.Button(buttons, text="Save", command=self.on_save).grid(row=0, column=1)
+        buttons.grid(row=4, column=0, columnspan=2, sticky="e", pady=(12, 0))
+        ttk.Button(buttons, text="Discard", command=self.on_discard).grid(row=0, column=0, padx=(0, 8))
+        ttk.Button(buttons, text="Save", style="Accent.TButton", command=self.on_save).grid(row=0, column=1)
         win.protocol("WM_DELETE_WINDOW", self.on_close_details)
         w["title"].focus_set()
         self.check_notes()

{bugcap-0.2.2 → bugcap-0.3.0}/src/bugcap/mcp_server.py

@@ -182,13 +182,13 @@ def build_server():
     @tool()
     def attach_image(id: int, sources: list[str], labels: Optional[list[Optional[str]]] = None) -> str:
         """Attach images (file paths, globs or http(s) URLs) to a report, with optional labels
-        (one per source, null for none). Notes can then refer to them as @1 or @label."""
+        (one per source, null for none). Notes can then refer to them as @i1 or @label."""
         with Store() as store:
             return json.dumps(agent_api.attach_image(store, id, sources, labels))
 
     @tool()
     def update_notes(id: int, notes: str) -> str:
-        """Replace a report's notes. @1 / @label references must point at the report's images."""
+        """Replace a report's notes. @i1 / @label references must point at the report's images."""
         with Store() as store:
             return json.dumps(agent_api.update_notes(store, id, notes))
 

{bugcap-0.2.2 → bugcap-0.3.0}/src/bugcap/refs.py

@@ -1,4 +1,10 @@
-"""`@` references in notes: `@3` (media index), `@login-error` (media label), `@@` (literal @).
+"""References in notes.
+
+`@` points at media, by kind letter and its number in the report: `@i3` image, `@v2` video,
+`@g4` animated GIF, `@f5` keyframes. `@login-error` is a media label and `@@` a literal `@`.
+The older `@3` form still reads as media 3, so existing notes keep working.
+
+`#N` points at report N (soft: an unknown number is kept as text and reported as a warning).
 
 References are ignored inside fenced code blocks, inline code spans and email-like text.
 Everything here is pure text processing; the rules for what a reference may point at
@@ -13,13 +19,19 @@ from .errors import ServiceError
 
 REMOVED_TEXT = "[image removed]"
 LABEL_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_\-]*$")
+MEDIA_LETTERS = {"image": "i", "video": "v", "animated": "g", "frames": "f"}
+# `v2`, `G4`, ...: a kind letter and a number. Labels may not look like this (see service.validate_label).
+INDEX_RE = re.compile(r"^([ivgfIVGF])([1-9][0-9]*)$")
+RESERVED_LABEL_RE = re.compile(r"^[ivgfIVGF][0-9]+$")  # any kind letter + digits, even i0
+_LEGACY_INDEX_RE = re.compile(r"^([1-9][0-9]*)$")
+_REPORT_RE = re.compile(r"(?:^|(?<=[\s(\[]))#([1-9][0-9]*)(?![\w\-])", re.M)
 _REF_RE = re.compile(r"@@|(?<![\w.%+\-])@([A-Za-z0-9_\-]+)(?![\w\-])")
 _FENCE_RE = re.compile(r"^ {0,3}(`{3,}|~{3,})")
 
 
 @dataclass
 class Ref:
-    token: str  # text as written, e.g. "@1", "@login-error", "@@"
+    token: str  # text as written, e.g. "@i1", "@login-error", "@@"
     start: int
     end: int
     kind: Literal["index", "label", "escape", "unknown"]
@@ -28,6 +40,14 @@ class Ref:
     def name(self) -> str:
         return self.token[1:]
 
+    @property
+    def key(self) -> str:
+        """What the reference points at: the image number for an index (`@i1` and `@1` both
+        give "1"), otherwise the name as written. Used to match rewrite mappings."""
+        if self.kind == "index":
+            return index_number(self.name) or self.name
+        return self.name
+
 
 def _blank(text: str) -> str:
     return "".join(ch if ch == "\n" else " " for ch in text)
@@ -103,8 +123,43 @@ def _mask_spans(text: str) -> str:
     return "".join(chars)
 
 
+def index_number(name: str) -> Optional[str]:
+    """`v3`, `I3` or the older `3` -> "3"; anything else -> None."""
+    match = INDEX_RE.match(name)
+    if match:
+        return match.group(2)
+    match = _LEGACY_INDEX_RE.match(name)
+    return match.group(1) if match else None
+
+
+def index_letter(name: str) -> Optional[str]:
+    """The lower-case kind letter of `v3` ("v"); None for the older `3` form."""
+    match = INDEX_RE.match(name)
+    return match.group(1).lower() if match else None
+
+
+def media_token(item) -> str:
+    """The reference that points at a media item as written in notes: `@i1`, `@v2`, `@g3`, `@f4`."""
+    return f"@{MEDIA_LETTERS.get(item.kind, 'i')}{item.idx}"
+
+
+def report_refs(notes: str) -> list[int]:
+    """Report numbers referenced by `#N` in the notes (code and emails excluded)."""
+    return [int(m.group(1)) for m in _REPORT_RE.finditer(mask(notes or ""))]
+
+
+def substitute_reports(notes: str, mapping: dict) -> str:
+    """Replace `#N` by `mapping[N]` where present (other `#N` are left as written)."""
+    out = notes or ""
+    for m in reversed(list(_REPORT_RE.finditer(mask(out)))):
+        number = int(m.group(1))
+        if number in mapping:
+            out = out[: m.start()] + mapping[number] + out[m.end():]
+    return out
+
+
 def _classify(name: str) -> str:
-    if name.isdigit() and not name.startswith("0"):
+    if index_number(name) is not None:
         return "index"
     if LABEL_RE.match(name):
         return "label"
@@ -123,10 +178,12 @@ def parse_references(notes: str) -> list[Ref]:
 
 
 def resolve(ref: Ref, media: list):
-    """The media item a reference points at (label match is case-sensitive), or None."""
+    """The media item a reference points at (label match is case-sensitive), or None.
+    `@v2` only matches a video; the older `@2` matches whatever item is number 2."""
     if ref.kind == "index":
+        letter = index_letter(ref.name)
         for item in media:
-            if item.idx == int(ref.name):
+            if item.idx == int(ref.key) and (letter is None or MEDIA_LETTERS.get(item.kind) == letter):
                 return item
     elif ref.kind == "label":
         for item in media:
@@ -136,7 +193,7 @@ def resolve(ref: Ref, media: list):
 
 
 def valid_tokens(media: list) -> list[str]:
-    indexes = [f"@{m.idx}" for m in sorted(media, key=lambda m: m.idx)]
+    indexes = [media_token(m) for m in sorted(media, key=lambda m: m.idx)]
     labels = [f"@{m.label}" for m in sorted(media, key=lambda m: m.idx) if m.label]
     return indexes + labels
 
@@ -158,8 +215,8 @@ def _rewrite(notes: str, mapping: dict[str, str]) -> tuple[str, int]:
     out = notes
     count = 0
     for ref in reversed(parse_references(notes)):
-        if ref.kind in ("index", "label") and ref.name in mapping:
-            replacement = mapping[ref.name]
+        if ref.kind in ("index", "label") and ref.key in mapping:
+            replacement = mapping[ref.key]
             if replacement != ref.token:
                 out = out[: ref.start] + replacement + out[ref.end :]
                 count += 1
@@ -167,7 +224,7 @@ def _rewrite(notes: str, mapping: dict[str, str]) -> tuple[str, int]:
 
 
 def rewrite_references(notes: str, mapping: dict[str, str]) -> str:
-    """Replace references by name (`{"2": "@1", "old": "@new", "3": "[image removed]"}`).
+    """Replace references by key (`{"2": "@i1", "old": "@new", "3": "[image removed]"}`).
     Code, emails and `@@` are never touched; other text is preserved exactly."""
     return _rewrite(notes, mapping)[0]
 
@@ -186,7 +243,7 @@ def references_to(notes: str, item, media_all: list) -> list[Ref]:
 
 
 def display_notes(notes: str, media: list) -> str:
-    """Notes for terminal display: `@1` becomes `@1 (images/…)` and `@@` prints as `@`."""
+    """Notes for terminal display: `@i1` becomes `@i1 (images/…)` and `@@` prints as `@`."""
     out = notes or ""
     for ref in reversed(parse_references(out)):
         if ref.kind == "escape":