GETTING STARTED

Desktop workspace

The PySide6 desktop application is a Python-first source-bundle editor and an evidence viewer for deterministic conversion.

Start here · Keyboard shortcuts · Diagnostics and results

Launch

pycforge-workspace

The equivalent module command is:

python -m pycforge.ide

Startup validation

The startup progress dialog advances through four real local stages. It checks the packaged vector resources, validates all offline Help sources, authenticates and parses every precompiled .ting Compact-IR rulepack, and then constructs the workspace. It uses the same PyCForge brand mark as the main title bar, Help, and About.

No simulated progress. Startup uses no timer or network request. Cancel is honored at the next safe stage boundary. If a required resource or rulepack fails validation, the dialog stays open with the precise failure and no partially initialized workspace appears.

Authoring and conversion

Open Python selects up to 64 explicit .py documents. Preview is read-only, paged, size-bounded, and never imports or executes a selected file.
New Module adds a plainly named unsaved module. A new workspace begins with no synthetic document; the first file opened or module created becomes primary automatically.
Close or Remove Module works for every tab, including the first and final tab. Closing the last document leaves a valid empty workspace; no mandatory main.py tab is recreated.
Save Python and Save Python As use guarded atomic publication.
Transpile Source Bundle converts every open logical module as one unit in an isolated, cancellable worker.
Function folding and indent guides. The larger Python gutter marker toggles one authenticated function, including nested functions and methods. Edit → Toggle Fold, Fold All Functions, and Unfold All Functions provide direct menu access; the source-header controls fold or unfold all functions as well. Small documents fold immediately. For larger source, Fold All reports that analysis is running and completes from the authenticated background structure result; it never starts a full parser on the UI thread. Subtle indent guides remain Python-only; neither feature changes generated C.
Generated C is immutable in the workspace. Set C Destination and Save Generated C publish only a fresh successful result.

Understand conversion state

State	Meaning	Permitted action
Current	Generated C corresponds to the active authenticated source bundle and contract identities.	Inspect or explicitly save it.
Stale	Source or an identity changed after the last successful conversion.	Review the prior result, then transpile again before saving.
Rejected	The complete unit did not satisfy a syntax, semantic, proof, resource, or conformance rule.	Use the coded diagnostic and remediation.
Cancelled	Conversion was interrupted as a control outcome.	Start a new conversion when ready.

Inspection surfaces

Diagnostics include source spans and remediation. Summary, decision trace, telemetry, source mappings, outline, bundle search, session history, breadcrumbs, and ForgeLens Python↔C highlighting expose what was proved and where generated text came from.

ForgeLens is passive. It does not change source, generated output, conversion state, or module selection. Mapping highlights support inspection only.

After a converted or rejected decision, the compact status-bar Ting button opens a read-only terminal-style dialog. Its overview and six agent tabs expose source-free evidence, exact gaps, rulepack identity, and bounded execution metrics. The shadow review never changes or authorizes the converter result.

Presentation and remembered state

Python source defaults to 14 pt; generated C defaults to 12 pt. View → Increase Python Text Size, Decrease Python Text Size, and Reset Python Text Size affect Python source only. View → Code & Editor Settings configures Python and generated-C text independently from 8–48 pt and retains the passive ForgeLens preference.

Ordinary non-editor controls use the exact reviewed menu font: a readable 12 pt minimum while respecting a larger Windows accessibility choice. The Source Bundle, Python Source, and Generated C caption bands intentionally use a compact 10 pt hierarchy to return working height to the editors. Python-header module and path values share the available width and elide in the middle when necessary; their complete values remain available as descriptive text. Python and generated-C editors remain the only scalable code surfaces. Help body text stays at 12 pt with a compact 12–14 pt heading hierarchy. Windows and dialogs are fitted to the current monitor work area so Windows display scaling cannot restore them beyond the usable screen.

The Open dialog no longer borrows the 14 pt Python-editor preference. Its read-only monospaced page preview uses the menu point size and compact page spacing so substantially more source remains visible. Transpilation Details always starts hidden. Opening it replaces the editor area with a full-height review surface; closing it, or activating a diagnostic or mapping location, restores the applicable editor.

Window layout, panes, visible views, recent paths, and custom Open/Save dialog geometry, columns, splitter, directory, and selection are remembered. Presentation-settings schema 3 discards the faulty schema-2 global font and oversized window geometry while preserving compatible session and path state. Accepted Python and generated-C code sizes are also mirrored as durable editor preferences so presentation cleanup cannot reset them on restart.

Ordinary typing updates document markers and conversion-state chips without rewriting the lower-left status message on every character. That persistent status area is reserved for meaningful open, save, conversion, and error events. Menu and toolbar action descriptions never appear as transient status text in that bottom bar.

Session restoration

Only linked Python files that remain open when PyCForge exits are reopened in their prior order, and the prior active saved file is reselected. Unsaved buffer contents are never serialized. Closing the final tab persists an intentionally empty restart session. File → Open Recent → Clear Recent Files clears only the convenience history: it neither closes current tabs nor changes which open files will be restored at restart. Missing, unreadable, or non-file paths remain absent and appear with their precise reason in a selectable workspace-restoration report. A restored Open preview appears only when its file row is visibly selected.

The custom main titlebar elides long document identities before the window controls so title text never enters the minimize, maximize, or close targets. In Find and Replace, Previous and Next stay together as one compact navigation group even while the Replace and Replace All row is visible.

Custom PyCForge titlebars

Every application dialog uses the same flat custom PyCForge titlebar and brand mark. Resizable dialogs provide custom maximize/restore and edge resize targets; the titlebar reserves a dialog-owned toolbar slot for future direct icon actions. Native steel-gradient dialog backgrounds are not used.

Recommended review workflow

Open or create the complete intended source bundle.
Confirm logical module names and designate the primary module.
Transpile, then review all diagnostics even when C is produced.
Inspect the summary, decision trace, mappings, and helper inventory.
Save generated C to a deliberate destination only while state is current.
Record the source bundle and result fingerprints for reproducibility.