Bring the README and HISTORY up to the fleet structure

[ptr727]

LETTER readme: the intro line is 150 characters, over the 100-char limit (Docker Hub's short-description cap, the tightest surface it feeds) - tighten it to one short sentence
LETTER description: the Docker Hub short description ('Pre-process media files for import into photo management systems.') does not match the README intro - set it from the README

The README was also missing three sections spec/readme-structure.md requires: Build and Distribution, Table of Contents, and Questions or Issues.

The intro

One 78-character link-free sentence: An application that prepares photos and videos for import into photo managers.

That is the single canonical short description, carried by the README, the GitHub About panel, and the Docker Hub short description alike (GOVERNANCE.md "Repository Details"). The implementation language is deliberately not in it: the line tells a reader what the thing does, and .NET is an implementation detail that belongs in Overview, alongside the three named systems (Lightroom, Immich, PhotoPrism) the cap forced out.

It is applied to six sites in one pass so the surfaces cannot drift:

Surface	File
README intro	README.md:3
--help transcript	README.md:97
HISTORY twin	HISTORY.md:3
Docker Hub overview	Docker/README.md:3
Docker image label	Docker/Dockerfile:38
Root command description	PhotoCleaner/CommandLine.cs:48

The last two matter because the README quotes --help verbatim, so the transcript was wrong the moment the intro changed. AGENTS.md keeps the fuller ".NET 10 console application" framing in its project intro, which is orientation for an agent rather than the canonical description.

HISTORY.md mirrors the title and intro as the README's twin, and its Release History replaces the stale "formal release notes have not been published yet" with the 1.0 entry, since 1.0.9 shipped on 2026-07-23.

Structure

• Build and Distribution, listing the three channels this project ships, with Build Status, Releases, and Release Notes sub-sections.
• Table of Contents, with <!-- omit from toc --> on the headings above it.
• Questions or Issues, before Development Environment Setup.
• Development Tooling renamed Development Environment Setup, the name the spec's slot 10 uses.
• Workflow Example moved ahead of Questions or Issues so the tail follows the section order.
• Link definitions grouped under <!-- Shields -->, <!-- Repo -->, <!-- External -->, alphabetized within each group.

Two bugs found in review

• No organize subcommand exists. CommandLine.cs:55-59 registers process, undo, import, index, trash. Every copy-pasteable Docker example invoked organize, so all four were broken; import is the one declaring --outpath. Fixed, along with a stale comment and a heading that would have sent a reader looking for the command again.
• Six inline URLs where the reference-style rule applies. All converted; outside the Table of Contents the README now carries no inline link.

Shields, and why only Docker Hub

The repository is private for now, so shields.io cannot read its GitHub release, build, or commit data and every GitHub-sourced badge would render broken. The pre-existing License shield was already broken for that reason and is kept rather than silently dropped. The repo goes public once the conformance work settles, and the GitHub build and release shields land at that flip. Recorded in the registry driftNotes and raised as a spec question in ProjectTemplate#508, since a repo is often private precisely while its README is being written.

Verification

• markdownlint-cli2 over **/*.md: 0 issues in 9 files.
• cspell over README.md + HISTORY.md (the CI file list): 0 issues.
• editorconfig-checker exits 0; files ASCII-clean and CRLF.
• C# was touched, so the full post-change set ran: CSharpier, build (0 warnings, 0 errors), dotnet format style --verify-no-changes, dotnet test (324 passed, 0 failed), dotnet husky run.
• Intro measures 78 characters, single sentence, link-free, identical across all six surfaces.

Part of the conformance sweep against the hub baseline (audit run 2026-08-01T15:30:19Z | hub 6501479).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 44.96%. Comparing base (30434d0) to head (efaf783).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop      #30   +/-   ##
========================================
  Coverage    44.96%   44.96%           
========================================
  Files           25       25           
  Lines         3398     3398           
  Branches       259      259           
========================================
  Hits          1528     1528           
  Misses        1824     1824           
  Partials        46       46           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR standardizes the repository’s public-facing documentation by tightening the shared short description and reshaping README.md/HISTORY.md to match the expected fleet README/HISTORY structure.

Changes:

• Shorten and unify the intro line in both README.md and HISTORY.md.
• Add required README sections (Build and Distribution, Table of Contents, Questions or Issues) and reorganize link definitions.
• Update HISTORY.md to include an initial Version: 1.0 release entry.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
README.md	Reworks README structure and link-definition layout; updates the canonical short description.
HISTORY.md	Mirrors the new short description and replaces the placeholder release-history text with a 1.0 entry.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (3)

README.md:630

• This heading ends with an extra " character (**:"), which renders oddly in Markdown and looks like a typo.

**Run [immich-go][immich-go-link] to import photos into Immich**:"

README.md:604

• This heading ends with an extra " character (**:"), which renders oddly in Markdown and looks like a typo.

This issue also appears on line 630 of the same file.

**Run [Immich CLI][immich-cli-link] to import photos into Immich**:"

HISTORY.md:3

• AGENTS.md specifies that README.md and HISTORY.md must share the exact same # PhotoCleaner title and one-line intro. README's title now includes <!-- omit from toc -->, but HISTORY's does not, so the titles no longer match exactly.

# PhotoCleaner

A .NET console application that prepares photos and videos for import into photo managers.

[ptr727]

Answering the three collapsed findings from the review on 4af8ec6, per the merge gate's requirement that low-confidence findings are investigated rather than left collapsed.

README.md:604 and :630, stray trailing " on two headings. Accepted, fixed in 14dbafb11abb82843817418613caeb7ca1add8c5. Pre-existing, and swept the whole set: six **Run ...**: headings in Workflow Example, only those two carried it.

HISTORY.md:3, titles no longer match exactly. Declined, this one is correct as written. spec/readme-structure.md specifies that HISTORY.md opens with "the same # <Title> (without the README's ToC-omit comment) and the same intro paragraph, copied verbatim", and says the audit compares them with HTML comments stripped. So # PhotoCleaner <!-- omit from toc --> in the README and # PhotoCleaner in HISTORY are the intended pair: the ToC-omit marker is instruction to the Markdown All in One extension, which only the README runs a Table of Contents for. Adding it to HISTORY would be the actual deviation.

The finding also cites AGENTS.md as the source of the same-header rule. That rule moved in #28: AGENTS.md is now the router, and the repo-local statement of this rule lives in CODESTYLE.md "Markdown and Spelling". The fleet-level rule it derives from is in spec/readme-structure.md, which is hub-only and not carried here, and that gap is raised upstream in ProjectTemplate#508.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (1)

README.md:7

• The PR description says the short description is now canonical across surfaces, but the README still contains (and the code still emits) the older description text. In this README, the $> PhotoCleaner --help snippet still shows "PhotoCleaner - Pre-process media files for photo management systems." (README.md:94-98), and the actual CLI description is still set to that string in PhotoCleaner/CommandLine.cs:48. The Docker image label also still uses "Pre-process media files for photo management systems" (Docker/Dockerfile:38). If the intent is to align the short description everywhere, those surfaces should be updated too (or the README should avoid presenting the --help output as verbatim until the CLI text is updated).

A .NET console application that prepares photos and videos for import into photo managers.

## Build and Distribution <!-- omit from toc -->

- **Source Code**: [GitHub][photocleaner-link], holding the source, the issues, and the CI/CD pipelines.

[ptr727]

The collapsed finding on the review of 14dbafb was right, and is fixed in c276f86958c89f8b7e214ad5bf8b7ce395ff9505.

The PR did claim one canonical sentence across surfaces while three others still carried the old text. Found a fourth beyond the two you named:

• PhotoCleaner/CommandLine.cs:48, the root command description
• Docker/Dockerfile:38, the image description label
• README.md:97, the --help transcript
• Docker/README.md:3, the Docker Hub overview, which you did not cite and which had a third variant of the sentence

All four now read the same sentence, so the --help transcript matches what the binary actually prints. Your framing of the choice was the useful part: either align the surfaces or stop presenting --help as verbatim. Aligning them is the better end state, since the transcript is the thing a reader copies.

Verified with the full post-change set rather than the build alone, since this touched C#: CSharpier, build (0 warnings, 0 errors), dotnet format style --verify-no-changes, and dotnet test (324 passed, 0 failed). markdownlint, cspell, and editorconfig-checker all clean.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Docker/Dockerfile:39

• The Docker image label description is missing the trailing period, so it no longer exactly matches the canonical short description used in README.md and PhotoCleaner/CommandLine.cs. Keeping these strings identical avoids subtle drift between help output, docs, and image metadata.

LABEL name="PhotoCleaner" \
      version="${LABEL_VERSION}" \
      description="A .NET console application that prepares photos and videos for import into photo managers" \
      maintainer="ptr727"

README.md:566

• This heading still says "organize" even though the subcommand and surrounding examples use import. Given the earlier rename from organize -> import, this wording is likely to confuse readers into searching for an organize command again.

**Run [PhotoCleaner][photocleaner-link] to organize new photos**:

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (1)

HISTORY.md:3

• HISTORY.md is described (and repo conventions expect) as a mirror of the README header, but the README title includes <!-- omit from toc --> while HISTORY's title does not. This makes the headers no longer identical between the two files.

# PhotoCleaner

A .NET console application that prepares photos and videos for import into photo managers.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (6)

Docker/README.md:3

• The Docker README intro should match the canonical short description stated in the PR description ("A .NET console application...") to keep the documentation consistent across README/HISTORY/Docker docs.

An application that prepares photos and videos for import into photo managers.

Docker/Dockerfile:38

• The PR description calls out a single canonical short description ("A .NET console application...") shared across README/About/Docker Hub. This Docker image label currently uses a different sentence, so it won't stay consistent with the documented canonical string.

      description="An application that prepares photos and videos for import into photo managers." \

README.md:3

• The PR description defines the canonical short description as "A .NET console application that prepares photos and videos for import into photo managers.", but the README intro currently omits ".NET console" and uses a different sentence. Update this line to match the stated canonical description so it stays consistent across surfaces (README/HISTORY/Docker/CLI).

An application that prepares photos and videos for import into photo managers.

README.md:97

• The help output snippet should match the canonical short description stated in the PR description (and the actual CLI string). Right now it repeats the non-canonical "An application..." sentence.

  PhotoCleaner - An application that prepares photos and videos for import into photo managers.

PhotoCleaner/CommandLine.cs:48

• This CLI description string should match the canonical short description stated in the PR description ("A .NET console application...") so README help output, GitHub About, and Docker Hub short description can stay in sync.

            "PhotoCleaner - An application that prepares photos and videos for import into photo managers."

HISTORY.md:3

• The PR description says HISTORY.md should mirror the README's canonical short description "A .NET console application...", but this line uses a different sentence. Align it to the canonical description.

An application that prepares photos and videos for import into photo managers.

[ptr727]

All six collapsed findings on the review of efaf783 are one issue, and it is a real one: they compare the code against this PR's description, which still quoted the previous sentence after the maintainer asked to drop the .NET console framing. The code was right and the PR body was stale, so the body is now updated.

Worth recording because the finding is correct in substance even though its direction is inverted: a PR description that names a canonical string becomes a seventh surface that string has to stay in sync with. The description now states the sentence once and tables the six code surfaces that carry it.

Canonical sentence is now An application that prepares photos and videos for import into photo managers. (78 characters), identical across README.md:3, README.md:97, HISTORY.md:3, Docker/README.md:3, Docker/Dockerfile:38, and PhotoCleaner/CommandLine.cs:48.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.