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

Activation: Effective immediately, before further conversion upgrades.
Scope: Every PyCForge project update, README edit, and release handoff.
Baseline: The approved README in PyCForge v1.3.45.
Project entry point: AGENTS.md in the source root requires this guideline.

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.
CC alone uploads PyCForge to PyPI, using CC's own computers. An assistant must
not publish PyCForge from its environment or move publication to another host.

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's only links are the following four exact URLs, each used once as
an image, in this order:

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.
Never remove any of these four image links, substitute past image links, or
restore older screenshots or banners. The top PyCForge banner and bottom
Crucible engine banner, including their exact URLs above, are permanent and
never change. Keep their positions and display widths unchanged.

Add no other image, navigation, badge, GitHub, documentation, mailto, local-file,
or relative link. In particular, never link to files inside the PyCForge
project from the README. Keep the contact email as plain code text.
Renderer-generated heading anchors are not authored navigation links.

4. Version and artifact checks

Previous publication mistake and standing clarification:
A previous PyCForge release was uploaded to PyPI with an incorrect old version
still displayed at the top of the README. When CC says "no need to update the
README" during PyCForge upgrades, that instruction applies to the prose and
other content. It never means leaving the top version number unchanged when
the project release version changes. Always update that number before building
the wheel and source archive CC will upload, even when it is the only README
edit. This clarification applies to future equivalent wording as well.

After every PyCForge update, always update the top README version to the actual
project release version when that version changes. This is mandatory even if
the README's information needs no other edits. Never treat unchanged README
content, conversion-only work, or an earlier freeze instruction as a reason to
leave an old version heading. A maintenance edit that retains the project
version must retain the matching heading.

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.

Only CC performs the PyPI upload, from CC's own computers. 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 any project update, including conversion work,
README changes, and release preparation. Keep AGENTS.md and this guideline in
the source root, carry both into the next source-maintenance workspace, and
include both in every future source archive. A maintenance-source update does
not replace an already published release or authorize a PyPI upload.

Historical release notes, specifications and evidence retain their original
context. They do not authorize reverting the current README, restoring past
image links, or retaining an old heading on a new release.
Keep the README/distribution verification tools aligned with these requirements.
Do not weaken checks or change approved URL constants to accommodate an
unrequested README edit. Review the prose as well as automated checks.
CC's later explicit instructions govern changes to this guideline.
