PyCForge README and Release Handoff Guidelines
Established by CC, 2026-10-19

Activation: Prepared for use after PyCForge v1.3.44 is published.
Scope: All future PyCForge README edits and release handoffs.
Baseline: The corrected README in the verified v1.3.44 wheel and source archive.

1. Purpose and structure

Keep the README a concise, professional introduction to PyCForge's working
features, installation, usage, supported conversion scope and practical limits.
Preserve the approved section order, feature emphasis, examples and contact
information. Make focused updates when documented capabilities or usage change.
Do not redesign, reorganize or broadly rewrite it without CC's instruction.
PyCForge is distributed through PyPI; it is not a GitHub project. Do not introduce
repository links, GitHub workflows or instructions that assume GitHub hosting.

2. Content boundaries

Do not place development cycle status, phase or milestone reports, internal
roadmaps, pending-work lists, test-run counts or release-engineering logs in
the README. Keep those in separate maintenance and verification documents.
Practical supported limits and accurately described engineering methods are
appropriate when they help users understand the product. Do not make unsupported
maturity, correctness, compliance or feature claims.

Keep the Conversion bug tracker. Record confirmed issues, concise corrections
and the actual version containing each fix. Do not change historical fix versions
when advancing the package version. The tracker is product information, not a
development progress report.

Maintain HTML Help as the detailed usage and coding reference. Keep its examples,
limits and diagnostics current during conversion work. Do not use HTML Help for
routine development cycle status.

3. Exactly four links

The README must contain exactly four external URLs, each used once as an image:

1) PyCForge banner at the top, display width 320:
https://res.cloudinary.com/vppzdwxg/image/upload/v1792314783/exec-76eda399-3547-4803-9896-4d57a7dd45cf.png

2) Existing workspace screenshot, retaining its accurate v1.3.39 label:
https://res.cloudinary.com/vppzdwxg/image/upload/v1792313873/pycforge-1.3.39-main.png

3) Existing Ting screenshot, retaining its accurate v1.3.39 label:
https://res.cloudinary.com/vppzdwxg/image/upload/v1792313993/pycforge-1.3.39-ting-evidence.png

4) Crucible banner directly below the Conversion bug tracker table, before
the engine description and contact line, display width 640:
https://res.cloudinary.com/vppzdwxg/image/upload/v1792420349/exec-7284d6da-a28b-4732-8980-a015c99067c6.png

Retain Crucible's subtitle: a py to c conversion engine.
Add no other image, navigation, badge, GitHub, documentation, mailto or relative
file links. Keep the contact email as plain code text. Renderer-generated heading
anchors are not authored navigation links. Change an approved asset only when
CC requests or authorizes that change.

4. Version and artifact checks

The README heading must match the release version in pyproject.toml, the imported
package, wheel METADATA, source PKG-INFO and both distribution filenames.
Installed workspace, startup, About and Help footer versions must also agree.
Historical screenshot labels and bug-fix versions retain their true identities.

Before handing off a release:
- Review the README diff against the approved baseline for scope and prose.
- Run the README renderer check and confirm the exact four images and placement.
- Inspect the finished wheel's METADATA and the source archive's README.md and
  PKG-INFO. Their README bodies must match the approved source README byte for byte.
- Run strict twine and public distribution checks on the exact final pair.
- Record each final filename, byte size and SHA256; include those hashes in the
  accompanying verification report and identify the final download pair clearly.

5. Release handoff

Keep one authoritative wheel/source pair for each release handoff. Preserve
review builds separately. If an unpublished version is rebuilt, explicitly state
that the new pair supersedes earlier downloads with the same filenames, provide
the new hashes, and make the current pair easy to distinguish.

CC performs the PyPI upload. Once a version is published, corrections require
an appropriately authorized new release version; do not suggest replacing or
deleting published files to reuse their names. A same-version instruction does
not authorize silently advancing the version.

When verifying publication, obtain current PyPI release metadata and compare
the published filenames and SHA256 values with the final handoff. Check the
published description separately. Investigate a mismatch using actual metadata
and archive contents before attributing it to caching or user error.

6. Ongoing maintenance

Consult this guideline before changing README.md or preparing release files.
Carry it into the next source-maintenance workspace and include it with future
source releases; do not rebuild the approved v1.3.44 upload files to add it.
Keep the README/distribution verification tools aligned with these requirements.
CC's later explicit instructions govern changes to this guideline.
