docs: product documentation, design working files, and the failed design review
Adds the required doc set under docs/mmd-pdf/ - PRD, feature backlog with status and sign-off per feature, screens with wireframes, test cases with the test data and the agent-tasking prompts, and the sign-off log. The sign-off log records the independent design review of 2026-08-27: DESIGN-FAIL, three blockers and five major findings, which is why every design feature in the backlog is blocked and the logo/token branch is unmerged. Design working files live in docs/mmd-pdf/design/ so the next agent can regenerate and re-render them. redplate.css there is the MMD shell design system lifted verbatim from the session that owns it - do not edit it. Also carries the session handover. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,169 @@
|
||||
# HANDOVER — MMD PDF (Windows PDF editor for staff)
|
||||
|
||||
**Written** 2026-08-27 15:18:53 +04 (11:18 UTC)
|
||||
**Session** mmd-projects-87 · **Repo** `gitea.baobab-ts.com/mmd-it/mmd-pdf`
|
||||
|
||||
---
|
||||
|
||||
## What this is
|
||||
|
||||
MMD staff had no sanctioned way to write inside PDF documents. PDFgear was
|
||||
blocked on 2026-07-20 for forging the Windows default-PDF registry setting.
|
||||
This session picked a replacement, proved it, forked it, and started turning it
|
||||
into an MMD product.
|
||||
|
||||
**MMD PDF** = GPL-3.0 fork of KillerPDF 1.7.5, staying GPL-3.0, `FORK-NOTICE.md`
|
||||
in the repo records what changed.
|
||||
|
||||
---
|
||||
|
||||
## What was done
|
||||
|
||||
### Chosen and proven (this part is solid)
|
||||
|
||||
- Surveyed open-source Windows PDF editors. **No MIT-licensed app does true
|
||||
inline PDF text editing** — the only genuinely MIT desktop option (every-pdf)
|
||||
can only stamp text on top of a page. KillerPDF (GPL-3.0) was picked; GPL
|
||||
restricts forking and redistribution, not internal deployment to staff.
|
||||
- **Passed the check that killed PDFgear.** `.pdf` UserChoice ProgId and Hash
|
||||
identical before and after install and after opening a PDF; the protective
|
||||
deny ACE intact; one signed executable, no helper binary. Read live from the
|
||||
registry on our own machine.
|
||||
- **Found and fixed a real defect.** Editing existing text left the original
|
||||
glyphs in the file — a delivery note corrected from 12 to 17 tonnes returned
|
||||
*both* figures from `pdftotext`. `Services/PdfRedactText.cs` now walks the
|
||||
page content stream, tracks the CTM and text matrix, and blanks every
|
||||
show-text operator whose origin sits inside the cover rectangle, before any
|
||||
new content is appended. Proven: after the fix the saved file contains only
|
||||
the new figure, every other line intact and still searchable.
|
||||
- **Built the test rig that found it.** `/opt/mmd-wintest/wintest` on the
|
||||
hypervisor: Xvfb + xfreerdp3 + xdotool, so every action is a real pointer or
|
||||
key event with no scripting back door. This is how user testing is done from
|
||||
now on.
|
||||
|
||||
### Dedicated Windows test machine
|
||||
|
||||
VM 203 on **mmd-fsn-03** renamed **mmd-win-test-01**, `onboot=1`, described in
|
||||
Proxmox. Windows Server 2022, 20 cores / 72 GB, guest 10.10.20.22. Its DNS was
|
||||
broken (no internet at all) — fixed. .NET SDK 8 installed for builds.
|
||||
It still also carries the Mali plant-station build, so it is shared.
|
||||
|
||||
### Design — failed review, not accepted
|
||||
|
||||
The rebrand and the new MMD shell design system ("red plate") were applied and
|
||||
merged **before any design existed**, which is the wrong order and Ben called
|
||||
it. Redone properly afterwards: design system pulled from the Claude Design
|
||||
project, red-plate stylesheet lifted verbatim from the session that owns it,
|
||||
seven screens composed at 800×600, then put through an **independent adversarial
|
||||
review** — the gate that was missing.
|
||||
|
||||
**Verdict: DESIGN-FAIL.** 3 blockers, 5 major, 3 minor. All eleven findings and
|
||||
the fix state are in `docs/mmd-pdf/SIGNOFFS.md`.
|
||||
|
||||
---
|
||||
|
||||
## Current live / verified state
|
||||
|
||||
| Thing | State |
|
||||
|---|---|
|
||||
| `main` | carries the rebrand + the redaction fix (PR #1, merged) |
|
||||
| `design/official-logo-and-tokens-20260827` | **bfb9845, pushed, NOT merged** — official logo + design-system values. Unaccepted: the design failed review. |
|
||||
| Build | `dotnet build -c Release`, 0 errors, on mmd-win-test-01 |
|
||||
| App | runs; opens, edits and saves correctly, keyboard-and-mouse tested |
|
||||
| Design | **DESIGN-FAIL**, no re-review run, no Ben sign-off |
|
||||
| Scanning | not written |
|
||||
| Signing / Intune | not started |
|
||||
|
||||
Claude Design project `446a3931-c345-48da-a3ac-246af02a2e52` ("Design System"):
|
||||
the repo's live CDS 0.3.40 was pushed into `mmd-portal/` (its mirror was stale
|
||||
at 0.3.11), and round-1 design pages into `mmd-pdf/`. **Round 2 was not pushed**
|
||||
— it failed review.
|
||||
|
||||
Two artifact links exist from before Ben's `/login` and are **dead**
|
||||
(`65c7726d…`, `e47d705f…`). Live under the current account:
|
||||
`7d8d6b56-ef36-4729-8e88-a3fb1392707e` (round-1 canvas) and
|
||||
`a7a974e8-aff4-49e6-b4cc-f80414769515` (status page). Both are round-1 and both
|
||||
predate the review — do not present either as reviewed.
|
||||
|
||||
---
|
||||
|
||||
## Resume steps
|
||||
|
||||
1. **Read** `docs/mmd-pdf/SIGNOFFS.md` for the eleven findings, then
|
||||
`BACKLOG.md` for what is ⛔.
|
||||
2. **Get Ben's toolbar pick** — A, B or C on the Directions board. The
|
||||
independent reviewer recommends **C** (three tabs; nothing hidden, every tool
|
||||
named). Nothing else in the design can be finished without it.
|
||||
3. **Apply the seven unapplied findings** — 1, 6, 7, 8, 9, 10, 11 — the big one
|
||||
being the rebuild of Main / EditText / PageRail / Nothing onto Direction C.
|
||||
Working files: `docs/mmd-pdf/design/build.py`, regenerate with `python3
|
||||
build.py`, render each `.dc.html` locally and look at it.
|
||||
4. **Re-run the independent review** with the prompt in
|
||||
`docs/mmd-pdf/TEST-CASES.md` under "To review a design". Give the reviewer
|
||||
the **complete** palette this time, including `#FAFAF8` and `#C9C6BC` — my
|
||||
incomplete brief caused half of finding 4.
|
||||
5. **Only after DESIGN-PASS**, publish the canvas and hand Ben the link for
|
||||
annotation. His annotation closes the gate; the reviewer's PASS does not.
|
||||
6. **Then** re-derive `Themes/MMD.xaml` from the signed-off design and merge
|
||||
`design/official-logo-and-tokens-20260827`.
|
||||
7. **Then** scanning (NAPS2.Wia, MIT, .NET Framework 4.6.2 — compatible with
|
||||
this net48 codebase), then signing, then Intune.
|
||||
|
||||
---
|
||||
|
||||
## Key facts, commits, addresses
|
||||
|
||||
- Repo `gitea.baobab-ts.com/mmd-it/mmd-pdf`; `main` = PR #1 merged;
|
||||
branch `design/official-logo-and-tokens-20260827` = **bfb9845**.
|
||||
- Hypervisor **mmd-fsn-03** — Hetzner dedicated, Falkenstein FSN1-DC16, auction
|
||||
#3049905, public 168.119.88.172, tailnet 100.64.0.19, Proxmox VE 9.2.10.
|
||||
Reach it with `ssh -i ~/.ssh/id_ed25519_mmd_fsn03_rescue root@100.64.0.19`.
|
||||
- Test machine **mmd-win-test-01** (VM 203), guest 10.10.20.22. Humans reach it
|
||||
in a browser at `https://plantpc.baobab-ts.com` (Guacamole, Entra SSO).
|
||||
- Source on the VM at `C:\src`; build output
|
||||
`C:\src\bin\Release\net48\MmdPdf.exe`; .NET SDK at `C:\build\dotnet`.
|
||||
- Graph for Intune/Entra: **MMD-CIO-Agent client secret** at
|
||||
`~/mmd-projects/entra-cio-agent/secret.env`, helper `graphlib.mjs`. The
|
||||
certificate in `~/.config/mmd/certs` is Exchange PowerShell only — do not
|
||||
reach for it and then conclude the agent lacks Intune access.
|
||||
|
||||
---
|
||||
|
||||
## Open items
|
||||
|
||||
- **Ben: pick the toolbar direction.** Blocks everything else in the design.
|
||||
- **Ben: the 16–24px app icon.** No official small MMD mark exists anywhere. The
|
||||
icon crops the lockup's baobab disc, which reads from 32px and is muddy below
|
||||
it. An agent must not draw a simplified one. Commission or accept muddy.
|
||||
- Seven design findings unapplied; no re-review run.
|
||||
- Scanning not written. Signing not started. Intune not started.
|
||||
- mmd-win-test-01's Windows evaluation licence — a restart reset it to 180 days,
|
||||
but it needs a real licence before it is a standing fixture.
|
||||
- Design round 2 not pushed to the Claude Design project (it failed review).
|
||||
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
1. **`Stop-Process` over WinRM against a running GUI app hangs the session.**
|
||||
Launch GUI apps with a *new* scheduled-task name instead.
|
||||
2. **`freerdp2-x11` does not exist on Debian 13.** It is `freerdp3-x11`, and the
|
||||
binary is `xfreerdp3`, not `xfreerdp`.
|
||||
3. **The word-mark was two literal `<Run Text="Killer">` elements**, not the
|
||||
product-name token — a global rename misses it. Check the title bar visually
|
||||
after any rename.
|
||||
4. **`redplate.css` belongs to another session.** It is lifted verbatim from
|
||||
their `build.mjs`. I edited it once chasing a review finding and reverted it.
|
||||
Do not edit it; raise a discrepancy with the owning session instead.
|
||||
5. **A `/login` mid-session orphans artifacts** published earlier under the old
|
||||
account. Republishing the same *file path* keeps mapping to the dead one —
|
||||
copy the file to a new path to claim a fresh URL.
|
||||
6. **`Ctrl+A` inside an inline text edit selects all annotations**, not the
|
||||
text. Use `End` + `BackSpace`. `Enter` commits, `Escape` cancels — the status
|
||||
bar now says so because both were guessed wrong.
|
||||
7. **Flatten is not redaction's friend.** It removes the old text by turning the
|
||||
page into a picture, destroying every searchable word. That is why the
|
||||
content-stream fix exists.
|
||||
8. **The design gate is not closed by a reviewer's PASS.** Only Ben's
|
||||
annotation closes it, and design that never went through the proper lane is
|
||||
an automatic fail however good it looks.
|
||||
Reference in New Issue
Block a user