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

Scope: Every PyCForge SDK README update and distribution preparation.
Baseline: The product-focused SDK 0.6.1 README approved by CC, with the SDK
banner added from the public Cloudinary URL supplied by CC.

1. Purpose and prose

Keep the README a clear, readable introduction to what the SDK offers and how
to use it. Follow PyCForge's direct professional prose. Explain the authoring
workflow, installation, engine selection, supported conversion scope, examples,
offline Help, and practical requirements without turning the README into an
engineering log. Preserve the approved section order and useful information;
make focused corrections as actual capabilities change.

Keep development-cycle status, milestones, internal roadmaps, pending-work lists,
test counts, verification logs, publication status, and release-by-release
history in separate engineering records. Practical platform and conversion
limits belong in the README when they affect the user's work. Do not claim
broader library, compiler, platform, or input coverage than is supported.

2. Human and AI use

State clearly that PyCForge SDK is designed for human developers and AI tools.
The desktop, command line, and Python API use the same project data, engine
services, verification rules, and packaging checks. Explain structured results
and diagnostic locations where they help automation. Do not imply that the
SDK includes an AI model or that AI-authored projects bypass verification.
Authors remain responsible for intended behavior and expected test results.

3. Capabilities and updates through PyCForge

Explain that the selected installed PyCForge supplies conversion operations,
starter projects, authoring forms, signatures, the SDK guide and import manuals
through its versioned Crucible workbench catalogue. The SDK keeps essential
first-run connection and recovery guidance locally. Ordinary compatible additions
should not require an SDK release; unsupported required interfaces must be stated
clearly rather than silently interpreted. Reconnect the SDK
after updating PyCForge. Compatible engine additions become available without
requiring a matching SDK release.

The SDK application is a separate installation. Changes to its desktop or
tools, and support for incompatible engine interfaces, may require an SDK
update. Connecting refreshes installed engine information; it does not download
or install either product. Reverify projects after SDK, engine, or compiler
updates. Describe automatic desktop discovery and manual location as its recovery path.
Preserve clear advanced interpreter-selection instructions, including Windows
python.exe, environment folders, This Python, and PyCForge's displayed path.

4. Approved banner and placement

Use this exact public image URL once at the very top of the README, above the
version heading and introduction:

https://res.cloudinary.com/vppzdwxg/image/upload/v1793376351/pcf_sdk_banner.png

Required image markup:
<img src="https://res.cloudinary.com/vppzdwxg/image/upload/v1793376351/pcf_sdk_banner.png" alt="PyCForge SDK" width="640">

Leave one blank line between the image and the heading. Preserve the image's
aspect ratio; do not specify a conflicting height. The approved banner uses
the previous PyCForge code-bracket icon with its copper slash, not the harpy
eagle. Preserve this exact banner URL, position, and display width unless CC
explicitly requests a change. Do not substitute a generated variant, a past
image, a temporary path, a private download URL, or a local file reference.

The SDK README is a separate document. PyCForge's four-image layout and image
URLs remain unchanged; do not copy them into the SDK README. The current SDK
README contains only its approved banner image URL. Additional images or links
require CC's direction rather than being added during routine maintenance.

5. Version and maintained content

Keep the heading in the form "PyCForge SDK VERSION" and align VERSION with
pyproject.toml, the package version, wheel metadata, source PKG-INFO, and both
distribution filenames. A request to preserve README prose never means leaving
an obsolete version heading when the release version changes. A prose-only
change to an unpublished release does not itself authorize a version increment.

Keep examples and stated coverage current. Remove obsolete exclusions when
engine support is added, and retain meaningful limits. A registered namespace
does not imply full conversion support for its corresponding Python library.
Keep the distinction between authoring, native verification, packaging, and
explicit registration clear. Keep detailed usage in offline Help and API
documentation; keep engineering history in its separate records.

6. Checks before distribution

- Review the README diff for product prose and the absence of development status.
- Check the exact banner URL, one occurrence in the README, placement before
  the heading, alt text, and width. Check that the public image loads and that
  the rendered README keeps the intended image and heading order.
- Check changed command and Python examples against the public SDK interfaces.
  Preserve prior valid evidence for examples that have not changed.
- Keep the README embedded in wheel METADATA and source PKG-INFO byte-identical
  to the maintained README. Run strict package metadata and archive checks.
- Include this plain-text guideline and AGENTS.md in every source archive.
  Keep AGENTS.md pointing to this file before future README or release work.
- Keep one authoritative wheel/source pair. If an unpublished pair is rebuilt
  under the same version, identify it as superseding earlier files and record
  the replacement hashes in the separate verification report.

7. Publication and preservation

CC alone decides and performs publication from CC's own computers. Do not
publish from an assistant environment or introduce GitHub hosting/workflows.
Preserve development materials, historical reports, and previous successful
artifacts. Keep release evidence and hashes outside the README.

Read this guideline before future SDK README changes or release preparation.
The earlier docs/README-GUIDELINES.md remains as supporting editorial context;
this plain-text file records the canonical banner and current README rules.
CC's later explicit instructions govern any changes to these requirements.

8. Section categorization — CC, 2026-11-04

Keep each section focused on its appropriate features, workflow or practical
requirements. UI/dialog issues do not belong in conversion bug tables. Routine
release history and verification results remain in engineering records. If no
product information needs changing, update only version references for an actual
SDK release. Do not add prose or advance the SDK merely to match PyCForge.
