# Prompt Cage 1.0.0 User Guide ## 1. Purpose Prompt Cage lets a person turn their own strict rules and research process into a reusable model workflow. It is designed for users who want consistent sessions across models, including small local models that struggle with long instructions, tool selection, folder management, or evidence tracking. The user controls five inputs: 1. An ordered protocol manifest. 2. One or more rule and process files. 3. Optional integration contracts. 4. Assigned working, target, and receipt folders. 5. The task to perform. Prompt Cage compiles those inputs into one model-ready brief. It also creates a session folder with five standard records, evidence and output folders, a hashed JSON receipt, and an append-only ledger line. Prompt Cage is agnostic. It does not include the creator's private behavioral framework, research rules, visual header, fixed paths, failure examples, or preferred model provider. ## 2. Requirements - Python 3.10 or newer. - Tkinter for the desktop window. Standard Windows Python installations normally include it. - A protocol folder containing `protocol_manifest.json` and its declared UTF-8 text files. - A target folder that already exists. - Write access to the working and receipt folders. No third-party Python package, online service, account, or network connection is required. ## 3. First setup ### Windows desktop setup 1. Extract the Prompt Cage folder. 2. Double-click `run_prompt_cage.bat`. 3. Set a project name and session prefix. 4. Select a working folder. Prompt Cage creates one numbered session folder per generated brief. 5. Select the target folder containing the material the model may inspect. 6. Select your protocol folder. 7. Select an integration folder, or clear the field if no integrations are used. 8. Select a receipt folder. 9. Select the supplied header and footer templates, or replace them with your own templates. 10. Click **Validate** before generating a live session. The first saved configuration is written to: ```text %USERPROFILE%\PromptCage\prompt_cage_config.json ``` Set the environment variable `PROMPT_CAGE_CONFIG` to use a different configuration path. ### Command-line setup Display all commands: ```text python prompt_cage.py --help ``` Print the resolved configuration: ```text python prompt_cage.py show-config ``` Validate the configured folders and manifests: ```text python prompt_cage.py validate ``` ## 4. Create a protocol pack Create a new blank pack from the command line: ```text python prompt_cage.py init-protocol "C:\Research\MyProtocol" ``` This creates: ```text MyProtocol/ protocol_manifest.json 01_RULES.md ``` Replace the placeholder text in `01_RULES.md`. Add more UTF-8 files and list them in the exact required order in `ordered_files`. ### Protocol manifest format ```json { "format": "prompt-cage-protocol", "version": 1, "name": "My Strict Research Protocol", "ordered_files": [ "01_RULES.md", "02_SOURCING.md", "03_CLOSEOUT.md" ], "phases": [ "Verify scope and folders.", "Read every protocol file in order.", "Execute retrieval and inspect supporting evidence.", "Verify deliverables and close out." ], "required_artifacts": [ "RUNNING_LOG.md", "FINDINGS.md", "AUDIT.md" ], "evidence_rules": [ "Cite the exact source for each factual claim." ], "prohibited_actions": [ "Do not claim a file was read without evidence." ], "completion_checks": [ "Match every completion claim to an artifact." ] } ``` The following file types are accepted as protocol text: `.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.toml`, and `.xml`. Each file must be UTF-8 text, must not be empty, and must be no larger than 2 MiB. The combined protocol text limit is 16 MiB. Symbolic links and paths that leave the selected protocol folder are refused. ## 5. Create integration contracts An integration contract tells the model how an external retrieval, trace, database, document, or validation tool must be used. It is not an executable plug-in. Prompt Cage includes the contract in the brief but never launches the integration itself. Create `integrations_manifest.json` in the selected integration folder: ```json { "format": "prompt-cage-integrations", "version": 1, "integrations": [ { "name": "Local Document Tracer", "purpose": "Return deterministic document matches and passages.", "instructions_file": "document_tracer.md", "required": true, "allowed_operations": [ "read the assigned corpus", "write results inside the active session" ], "forbidden_operations": [ "modify the source corpus" ], "required_evidence": [ "record the invocation", "record the exit status", "cite the result file and hash" ] } ] } ``` The instruction file should name: - The real program or tool name. - The allowed inputs. - The exact invocation shape or model-facing tool schema. - The output format. - The output location. - The required evidence. - The failure behavior. For small models, give the model one high-level integration action instead of many low-level commands. For example, expose `run_research_trace` with a structured question and search terms. A deterministic controller can translate that request into several tracer commands, save the results, and return one bounded evidence packet. ## 6. Header and footer templates Prompt Cage replaces these tokens wherever they appear in a selected template: ```text {{PROJECT_NAME}} {{SESSION_ID}} {{DOCUMENT_NAME}} {{TIMESTAMP}} {{SESSION_FOLDER}} {{WORKING_FOLDER}} {{TARGET_FOLDER}} {{PROTOCOL_FOLDER}} {{INTEGRATION_FOLDER}} {{PROTOCOL_SHA256}} {{MODEL_NAME}} {{EFFORT_MODE}} {{STATUS}} {{RECEIPT_PATH}} ``` Unknown tokens cause validation to fail instead of silently producing an incomplete header. ## 7. Generate a session ### Desktop 1. Enter the task in the task box. 2. Click **Validate**. 3. Click **Preview and copy** to inspect the complete prompt without writing a session. 4. Click **Generate session** when the prompt is correct. 5. Paste the compiled prompt into the selected model, or give the prompt file to an automated runner. The session number advances only after generation succeeds. ### Command line Preview without writing files: ```text python prompt_cage.py preview --task "Compare the declared sources and produce a cited findings table." ``` Generate from task text: ```text python prompt_cage.py generate --task "Compare the declared sources and produce a cited findings table." ``` Generate from a UTF-8 task file: ```text python prompt_cage.py generate --task-file "C:\Research\task.md" ``` Use another configuration file: ```text python prompt_cage.py --config "C:\Research\prompt_cage_config.json" generate --task-file task.md ``` ## 8. Generated folder structure For session prefix `RUN` and session number `1`: ```text working_folder/ RUN_0001/ RUNNING_LOG.md CONTEXT.md FINDINGS.md AUDIT.md TASK_LEDGER.md IGNITION_PROMPT_YYYYMMDD_HHMMSS.md evidence/ outputs/ transcript/ ``` The receipt folder receives: ```text RUN_0001_RECEIPT_YYYYMMDD_HHMMSS.json PROMPT_CAGE_LEDGER.jsonl ``` The receipt records the task hash, compiled prompt hash, protocol digest, every protocol and integration file hash, assigned folders, model label, session identifier, and scaffold files created. The ledger stores the receipt hash and the hashes needed to connect a session to its inputs. ## 9. Verify a session receipt ```text python prompt_cage.py verify-receipt "C:\Research\receipts\RUN_0001_RECEIPT_20261029_120000.json" ``` Verification checks that the compiled prompt still matches its recorded SHA-256 hash. It also reports any protocol or integration input that is missing or changed. A changed input does not rewrite the old receipt. ## 10. Embedding options **Embed protocol text** places the complete ordered rule files inside the prompt. This is the most reliable mode for models that cannot read local files. When embedding is disabled, the prompt contains the ordered file inventory and hashes, then requires the model to read each file before task execution. Use this only when the model has reliable file access. **Embed integration text** works the same way for integration contracts. **Create session scaffold** creates the five standard records and evidence folders. Disable it only when another controller creates equivalent artifacts. ## 11. Recommended structure for small models Small models perform better when the controller makes workflow decisions and the model handles bounded language tasks. A reliable arrangement is: 1. The user fills one structured task form. 2. Prompt Cage loads and hashes the selected protocol pack. 3. A deterministic controller creates the session and runs a fixed retrieval plan. 4. Data or chat tracers return bounded JSON evidence packets. 5. The model receives only the question, the protocol rules, and the selected evidence packet. 6. A verifier checks every cited result identifier and file reference. 7. The controller writes the report, receipt, result tables, and closeout state. This avoids asking a small model to choose among many tools, repair command syntax, manage folders, or remember which evidence has already been retrieved. It also keeps deterministic counts separate from model interpretation. ## 12. Using Prompt Cage with Data Tracer or Chat Tracer Create one integration contract that describes a high-level controller such as `run_research_trace`. The controller, not the model, should perform the detailed sequence: 1. Validate or initialize the tracer workspace. 2. Intake or select the assigned corpus. 3. Run a fixed query expansion policy. 4. Run trace, audit, count, passage, or comparison steps in a declared order. 5. Save raw machine-readable results before summarization. 6. Export result tables and verify the receipt ledger. 7. Return a bounded evidence packet with stable result identifiers. The model should receive two actions at most: request a trace packet and submit a cited answer. Models without native tool calling can return one JSON object. The controller validates that JSON and performs the operation. ## 13. Safety and preservation behavior - Prompt Cage refuses protocol paths that escape their assigned folder. - Prompt Cage refuses symbolic links as protocol inputs. - Prompt Cage refuses empty, oversized, unsupported, or non-UTF-8 inputs. - Prompt Cage never executes an integration contract. - Prompt Cage never deletes source material. - Prompt Cage refuses to generate a second ignition prompt in the same numbered session. - Existing scaffold records are preserved. - Receipts are new files and the master ledger is append only. The model receiving the prompt may have capabilities beyond Prompt Cage. Its runtime permissions must still be configured separately. ## 14. Troubleshooting ### Target folder does not exist Create the target folder or select the correct existing folder. Prompt Cage does not create a target data folder because that could hide a path mistake. ### Protocol file was not found Check `ordered_files` in `protocol_manifest.json`. Names are relative to the protocol folder and must match the real file names. ### Session already has an ignition prompt Increase the session number. Prompt Cage will not overwrite or mix two briefs in one session. ### Tkinter is unavailable Use the command-line interface or install a Python distribution that includes Tkinter. ### The model ignores the protocol Enable protocol embedding, reduce the number of rules, convert broad principles into explicit allowed and prohibited actions, and give the model fewer high-level integration choices. ### The model invents citations Use stable result identifiers in the integration output and require a deterministic answer verifier before the controller accepts closeout. ## 15. Distribution checklist Before sharing a customized Prompt Cage pack: 1. Remove private paths and example data. 2. Replace all placeholder rules. 3. Validate the protocol and integrations. 4. Generate one disposable session. 5. Verify its receipt. 6. Confirm the target corpus was not modified. 7. Document the model runtime and any external tools separately.