Create conversion extensions using the installed PyCForge engine. This short guide is available before an engine is connected.
The startup panel searches your saved connection and common Python installations. Choose among several engines, or use Locate PyCForge if it cannot be found. Select the installation, Python environment, installed Crucible support folder or Python interpreter. The custom picker has drive shortcuts. A source folder alone needs a working installed engine.
Continue offline opens local projects and any cached reference. Engine and tools exposes advanced interpreter and compiler settings. This Python selects the SDK interpreter; Refresh checks it. PyCForge’s About → Distribution → SDK Python shows its exact interpreter.
After connection, the Help topic selector offers the SDK guide and conversion-import manuals supplied by PyCForge’s Crucible folder. Authoring forms, operation choices and starter projects also come from that installation. Refresh after updating PyCForge. Cached guides remain readable offline; their engine and connection state are displayed above.
Open Engine reference → Conversion coverage to see the advertised families, profiles, exact operation signatures, limitations and starter choices. Search the tree or select a profile. The Authoring methods tab explains the public calls. Python and command-line clients use the same SDK.coverage() and coverage report. Older engines may supply forms and starters without a family overview; that missing metadata is labeled. Browsing cached coverage never approves verification or packaging.
Choose New, then Use walkthrough or Create directly. The walkthrough covers Starting point, Project location, Package identity, Export names, and Review and create. Required fields are marked with an asterisk. Back and switching creation modes preserve the current entries. Your entries for each starter are also retained while this dialog remains open.
Use Remember this creation mode to remember your choice after successful creation. You can switch modes in every new-project dialog. Create project uses the same public SDK service as command-line and Python clients. Engine errors leave the setup open for correction.
Save setup keeps incomplete choices in a .pcfsetup file. Open setup restores those choices and your place in the guide, even offline. Save setup as keeps a separate copy. Closing with unsaved changes offers Save, Discard or Keep editing. Standard Open, Save and Save As keyboard shortcuts work in this dialog.
If another program changes the saved file, open it again or save your current edits under a new name. Review current starter explains changed engine data and retired exports before you choose whether to apply it. Missing starters remain visible; they are never replaced automatically. Creation requires current engine data. Saved setup is retained after creation; open the created project normally to continue authoring.
Creation opens the ordinary project in Edit extension. Guided creation continues with focused authoring steps. Existing projects offer Use authoring guide; Edit directly returns to the same fields in normal tabs. Package, function and constant Help have separate guided steps. Back, the step selector and switching views preserve edits.
The authoring guide remembers the selected step and item for each project. This is navigation recovery, not autosave: use Save for project edits. Save those edits before opening fixture source, which has its own Save action. After changing exports or operations, review matching Help and source examples explicitly. Missing Help fields can be added through Tools after saving.
The final authoring step lists project contents without approving them. Open Scanner only navigates. Scan, Check fixtures, Verify fixtures, Package and registration remain explicit workspace actions; navigation and Help do not compile or run fixtures.
An engine field missing from an older project appears as Set value. Read its engine description, choose a value explicitly, then Save and Scan. Opening or canceling the dialog inserts no default. Advanced project data preserves values outside the advertised form.
Choose New or Open, edit the declaration and Help, save, then Scan. Check fixtures reviews conversion expectations for all saved fixtures without a compiler or program execution. Expected rejection codes are checked as well as successful conversions. Double-click a result to open its source at the reported location. Verify fixtures explicitly converts, compiles and runs the saved examples; preflight does not validate native outputs or approve packaging. Ready to package means the current saved project matches passing evidence for its declared fixtures and recorded environment. Package and registration are separate actions. Changes to projects or tools require fresh verification.
After Scan, concise next-action buttons explain the available steps. Choose an action explicitly; receiving a result does not start verification or packaging. Unsaved edits clear these recommendations along with readiness.
After Package succeeds, the Scanner shows the exact namespace, a copyable *import statement and a read-only Help example that passed verification. Its expected result is available beside the source. Viewing or copying these does not run anything. Full package hashes and input identities remain under Evidence.
Register package opens the normal file picker at the built package and requires your explicit confirmation. You can choose another file; the receipt reports that file’s actual namespace and engine result. After registration succeeds, select Runtime in PyCForge and consult Import Help for the supported operations. A rejected registration displays the engine’s reason and no usable import statement.
Activity contains diagnostics. Unsaved edits and outside file changes clear readiness. A failed refresh preserves compatible cached reference; it cannot authorize execution. Closing during work requests cancellation and waits for the worker. Windows direct-process termination does not supervise arbitrary descendant process trees.
In Fixtures, choose Add, Duplicate, Rename or Remove. Add separates the fixture name, new source and independently chosen expectations. Choose Review change, inspect the source and Help links, then Apply change. Applying saves immediately; it does not run the fixture. Duplicate creates a new source file with the same expectations. Rename changes the fixture name and linked Help examples while keeping its source filename. Remove keeps the source file on disk; linked Help requires an explicit replacement native example. Existing files are never overwritten by these actions.
After Verify fixtures, select a row under Fixture results. Expected and actual output are shown side by side, with escaped whitespace by default. Open source and Edit expectation navigate to your inputs. Judge the intended behavior independently: recorded output is not automatically correct. Save and verify again after edits. Recorded details retains the full result.
In the fixture source editor, Save repair as… saves the original source and your edited text to a separate .pcfrepair file outside the project. Reopen it with File → Open source repair, even when the project is unavailable. This is an explicit checkpoint, not autosave.
Review changes shows the original, edited and current source and current fixture expectations. Reconcile the edited text yourself, review again, then choose Apply repair. Another disk or draft change blocks the old review. Expectations remain independently authored; run Scan and Verify fixtures afterward. Project-form edits and unsubmitted Add fixture drafts are not included in this checkpoint.
File → Save project draft checkpoints project fields, Help, expectations and authoring position to a .pcfdraft outside the project. The fixture dialog can save unsubmitted inputs, including both expectation modes. Advanced project data can checkpoint incomplete JSON.
Open project draft works without an engine or available project. Review Original, Edited JSON and Disk before choosing Resume editing or Save reviewed project. Only the latter writes project.json. Unfinished fixtures continue through File → Resume unfinished fixture and their own review/apply. Review current draft reconciles external changes while retaining your current buffer. Failed checkpoints keep edits open.
Checkpoints are explicit saves, not autosave or whole-project backups. Missing source/project files need separate restoration. Small Set value dialog inputs must first be applied to the editor. New checkpoints require a filesystem supporting hard links. Existing conflict checks and separate project/source saves remain; no automatic merge or verification is performed.
Ctrl+N: New; Ctrl+O: Open; Ctrl+S: Save; F5: Scan; Shift+F6: Check fixtures; F6: Verify fixtures; Ctrl+B: Package; F1: Help.
With PCFC11, verification also records its external GCC executable. A changed or missing backend requires fresh verification. Use a compatible engine and driver, or select GCC directly on an older engine.
In New, choose Customize package identity and exports to set the package ID, import namespace, version and export names. The selected engine updates the fixtures and Help together. Review the generated files, add tests for your intended use, then Scan and Verify fixtures before packaging. This needs a live engine that advertises starter customization; older engines still provide unchanged starters.
Run pycforge-sdk manual from this Python environment for the authoring guide, public Python API and native diagnostic contract, even before connecting an engine. Add --topic diagnostics for compiler codes, coordinate conventions and failure handling. Detailed operation capabilities remain in the selected engine reference.
Native verification preserves PCFC11 structured records and retains the generated C for failed fixtures under the project’s .pycforge-sdk/native-failures folder. A reported error or incomplete diagnostics cannot approve packaging.
AI and script clients can use reference for the complete engine authoring reference and fields PROJECT --function EXPORT for focused definitions, choices, paths and presence. Add --json for structured results, or --offline to these commands to read compatible cached data without invoking an engine. Readiness JSON includes advisory next actions and their effects. Execution remains explicit.