# Tlamatini instructions for Codex and every coding agent ## HEADLESS IS FORBIDDEN. ALL EXECUTION MUST BE VISIBLE. Angela reaffirmed this mandatory repository rule on 2026-09-23. Read [TestsVisiblesAndVisibleExecutionFromClaude2Codex.md](TestsVisiblesAndVisibleExecutionFromClaude2Codex.md) before executing anything. This applies to every automated test, command, diagnostic, script, build, agent, prompt, CMD/PowerShell session and browser. - Run in a **visible, forked foreground window on Angela's real desktop**. Keep consoles and browsers visible while the work runs, and leave the console open afterward so its output can be read. Use PowerShell `-NoExit` or CMD `/k`. - Browser automation must explicitly use **`headless=False` / `headless: false`**. Never rely on a browser library's default. Headless mode is forbidden for CI, smoke checks, diagnostics, long runs and all other execution too. - With Tlamatini's Executer/Pythonxer, use `execute_forked_window: true`; with `execute_file`, request `foreground=True`; with Playwrighter, use `headless: false` and sufficient `hold_open_seconds` for inspection. - Never use hidden/minimized windows, `run_in_background`, detached jobs, `CREATE_NO_WINDOW`, `DETACHED_PROCESS`, or `-WindowStyle Hidden` to perform the requested work. A saved log or screenshot is not a substitute for visibility. - Verify that the actual window is visible on the interactive desktop before running the workload. A PID, successful launch call, or activation request alone does not establish that. **If visibility cannot be confirmed, do not execute the workload; explain the limitation to Angela.** - Monitor long runs live. Read the live transcript every 5–15 seconds, report meaningful progress or failures, and inspect the first error and application log. Record the exit code and final result; never report unseen work as watched. - Every new skill, runbook, harness and execution example must preserve this rule. Legacy headless flags must be refused loudly and must never enable a hidden browser. Review launch sites and fallbacks, not only default settings. The linked policy contains the concrete launch instructions. It governs development and verification, including tests of background product implementation. It does not require additional end-user service windows. ## Product UX boundary — clarified by Angela on 2026-09-27 The visibility rule governs our development work and verification. It must not be imposed on end users as extra application windows. Internal chat dictation runs without a separate console or foreground activation; its status belongs in the chat and its diagnostics in Tlamatini's main console/log. Verify this product behavior from a visible development console. Do not reintroduce a persistent Whisperer PowerShell/conhost window or require its visibility to enable recording. ## Existing repository contracts Read [CLAUDE.md](CLAUDE.md) and relevant documents indexed by [docs/claude/INDEX.md](docs/claude/INDEX.md). Preserve unrelated local edits. Never rewrite Git history. Do not modify the protected database backup/restore mechanics unless Angela explicitly requests it in the current turn. ## Compact mode is a real switch (2026-10-02) Since 2026-10-02 (shipped in `v1.75.0`, tag at `f7eb53ff`) the chat toolbar's **Compact mode** box (`#compact-mode-enabled`; `agent/compact_mode.py`, model `CompactState`, migration 0211) rewrites the REAL Configure rows: - Ticking it unticks every MCP, tool, agent and skill row (Config ▸ Configure MCPs, Configure Agents, ACPX-Skills) except **System-Metrics, Files-Search and Current-Time**, and pauses the External MCPs (the active list is saved, then restored). The user ticks back only what she needs; a Compact request binds exactly the ticked tools. Unticking it ticks EVERY row again. - **STRICT = locked ON:** a model that cannot hold everything activated switches the box ON by itself and locks it (greyed, 🔒); the server refuses a forged untick. A big model unlocks it and keeps Compact ON until the user unticks it. - Saved Configure dialogs apply at once (`compact_mode.after_toggles_saved`); there is no "restart the agent" any more. The old Compact badge and ACPX lock are gone: ACPX tools ride along only when their rows are ticked AND the toolbar's ACPX box is on. - The gauge legend reads **CONTEXT-WINDOW** and may pass 100 % (`OVER`); a cut request shows `CUT · read X of ≈Y tokens`, and its answer carries a CONTEXT-WINDOW warning line. The Configure dialogs price every row (`compact_costs.js`, `GET /agent/compact_mode/costs/`). - Register every new built-in tool in **`tools.tool_gate_table()`**, the one gate list that binding, Compact mode and the cost labels read. - A model's VERDICT (`compact_mode.VERDICT_KINDS`: `capacity`, `self_modify_fit`) updates every tab's box and stops there; it must never re-send rows or re-measure, or two pages on two models ping-pong forever (2026-10-08, `v1.76.0`). Contract: [CLAUDE.md](CLAUDE.md) → *Compact mode*, `docs/claude/architecture.md` → *Compact mode*, `docs/claude/recent-fixes.md` (2026-10-02). ## Self-modify is a switch, only where it exists (2026-10-03) The chat toolbar's **Self-modify** box (`#self-modify-toggle`, after Compact mode; `self_modify_switch.js`; `CompactState.self_modify`, migration 0212, ON by default) decides per request whether her self-knowledge (`Tlamatini.md`, 115,711 chars ≈ 28.9K tokens per request) is sent. It shipped in `v1.76.0` (commit `70aeeb87`, on `main` right after the `v1.75.0` tag). - **Who sees it:** `rag/config.self_modify_available()`. A source (dev) run of this checkout is ALWAYS self-able; a frozen build only when `build.py --self-modify` bundled `TlamatiniSourceCode/`. Otherwise the box and its script are not rendered at all (`{% if self_modify_available %}`). - **ON** sends the identity bullets and the whole `` section as before; **OFF** replaces the bullets with `SELF_MODIFY_OFF_NOTICE` (she must not read, edit or rebuild her own code) and drops the section. No marker is ever left in a prompt. - **Only when it fits:** a model that cannot hold it shows the box unticked, greyed and 🔒, and the server refuses a forged tick. Her choice is never rewritten; a big model unlocks it by itself. Compact mode's STRICT check is measured WITHOUT the self-knowledge. - ⚠️ **`build.py` ERASES `Tlamatini/db.sqlite3` and wipes `dist/`** before it builds. Never run it just to "test the frozen mode"; `FrozenPageTests` render the real chat page as a frozen build. Ask Angela before any real build. Contract: [CLAUDE.md](CLAUDE.md) → *Self-modify*, `docs/claude/architecture.md` → *The Self-modify switch*, `docs/claude/recent-fixes.md` (2026-10-03). ## v1.77.0 — first-person chat lines, the uninstaller keeps Templates (2026-10-09) `v1.77.0` (annotated tag at `052bfe0f`, pushed 2026-10-09) carries the two changes below; a build of `main` reports `1.77.0`. It was published on GitHub on 2026-10-09 (marked Latest), so self-update delivers `v1.77.0`. - **First person, by name.** Every fixed chat line Tlamatini sends (`agent/constants.py`) speaks in the first person and names the user (`display_name()` + `say()`; with no name the placeholder and its comma vanish). Several lines are recognised BY THEIR WORDS: change one and update `agent_page_ui.js`, `agent_page_chat.js`, `avatar.js`, `agents/teletlamatini/teletlamatini.py` and the harness markers in the same pass; the old phrases stay matched on purpose. - **Uninstaller.** `application`, `applications`, `content_generated`, `context_files`, `doc_generated` and `Templates` are kept whenever they hold a file; `Temp/` is erased; `agents/` is always kept (`uninstall.py::PRESERVED_WHEN_NOT_EMPTY`, commit `0520dc97`). An in-app update keeps the old `Uninstaller.exe`; only a new Installer replaces it. ## v1.76.0 — the Model Brain, a coloured console, honest PDF refusals (2026-10-08) `v1.76.0` (annotated tag, pushed) names the Model Brain. The tag points to `953ad2d8`; the Model Brain commit `72799950` landed right after it, so a build of `main` reported `1.76.0` (until the `v1.77.0` tag) and carried everything below. It was published on GitHub on 2026-10-09; self-update delivered `v1.76.0` until `v1.77.0` was published the same day. - **Model Brain** (`agent/model_brain.py`, `model_profiles.json`): every model is tuned from formal sources — an explicit `model_brain_overrides` entry, the sourced knowledge base, a profile learned once from Hugging Face for an unknown model, then Ollama's `/api/show`. `num_ctx` is clamped to the real context length, and thinking models get their own reasoning back inside the current tool loop. Config ▸ Models ▸ Save opens the Auto-tuning dialog; `model_brain: off` restores the legacy fixed sampling. Never hard-wire a model name, and never re-add the stall timers the Model Brain replaced. - **Console colours** (`manage.py::_ConsoleColorizer`, `console_colors`): the WINDOW is painted by level while `tlamatini.log` stays plain text; startup logs the console host (`--- [CONSOLE] host: …`). Windows Terminal is the default console on Windows 11, and Claude Code sets `NO_COLOR` for the programs it launches. - **PDF refusals say why:** when a second account signs in from the same browser, the upload goes out as that account; the chat now names the cause and says to reload (F5), the header comes back, the running step shows **Failed**, and the server logs `[PDF-CONTEXT] refused for user N`. - **Compact verdicts never re-measure** (`compact_mode.VERDICT_KINDS`): two chat pages on two models used to re-measure each other forever. - **File-Creator `append`** adds to the end of a file instead of overwriting it. Contract: [CLAUDE.md](CLAUDE.md) → *The Model Brain*, *The console is coloured by level*, *A refused PDF says why*; `docs/claude/recent-fixes.md` (2026-10-08). ## Prompt Flow comments are static; User Input runs (2026-10-03) **Commentary/Input contract (2026-10-04, shipped in `v1.76.0`):** Seven executable operations remain separate from static **User Commentary**. **User Input** (`user_input`) keeps the question/reply/cancellation mechanism and notched figure. **User Commentary** (`user_commentary`) is edited entirely on the canvas: double-click/Enter writes in the bubble; a floating mini toolbar formats selected text with different fonts, sizes, text colors, bold, italic and underline within the same note. With a caret, formatting applies to newly typed text; outside editing it applies to the whole note. Bubble color and alignment affect the note. There is no commentary configuration dialog or numeric dimension form. Drag any border or corner to resize, including while editing; Fit text removes spare height. Done/Ctrl+Enter saves; Cancel/Escape restores the whole edit. Ctrl+Z/Y works inside the editor; completed edits, moves, resizes and duplicates use flow Undo/Redo. Bubbles contain their full wrapped text without internal scrollbars. Version 2 files persist allowlisted `runs` plus matching literal `text`; older plain notes normalize to one run, and version 1 executable commentary still migrates to User Input with IDs/edges/settings intact. Comments have no ports/Start/runtime/context/history/step effects. The draft key remains `.draft.v1.`. Cache suffix: `-flow-file-opening-2`. See `docs/prompting-flow-designer.md` and the 2026-10-04 verification record; the October 4 local release-validation campaign tracks subsequent isolated frozen builds and runtime acceptance. Preserve this distinction when editing the designer, importing legacy diagrams, writing documentation or verifying the shipped example. The user explicitly rejected internal commentary scrollbars. Automatic containment must include font/width changes, inline typing, file/draft recovery and canvas Fit. ## Prompt Flow Run output resizing (2026-10-04) **Run output layout (2026-10-04, shipped in `v1.76.0`):** Drag the horizontal divider to give Run output 5–95% of the combined canvas/output pane height, excluding fixed headers, status and divider (initial share: 20%). Each pane scrolls independently; resizing preserves zoom, node geometry and text size. Up/Down changes one percentage point, Shift+Up/Down five, Home/End selects 5%/95%. Escape, blur or pointer cancellation ends a drag. Collapse/reopen and window resizing retain the ratio. The per-user `tlamatini.prompting-flow.layout.v1.` preference is separate from flow files, drafts, dirty state and Undo/Redo. Keep the native details log viewport explicitly sized so its scrollbar remains usable. See `docs/changes/2026-10-04-run-output-resize.md`. ## Windows flow-file lifecycle — 2026-10-04, shipped in `v1.76.0` Both `.flw` agent flows and `.fpmt` prompting flows now have Windows registration, repair, removal, status and Default Apps handling. Explorer/source command-line opening validates a bounded snapshot, reuses a matching running server before database startup, and returns through login to the correct editor without execution. Main-chat Open/drop/Reopen routes both formats into separate editor tabs while preserving the chat document. The historical `.flw` installer wrappers cover both types for old installer/uninstaller binaries; independent management uses `flow_file_associations.ps1 -Extensions`. Never erase UserChoice or another application’s Open With entries. Update Repair respects explicit unregistration and installation ownership. See [Windows flow files](docs/windows-flow-files.md). Cache suffix: `-flow-file-opening-2`. Committed to `main` on 2026-10-04. The October 4 local release-validation campaign also rebuilds isolated frozen artifacts; its dated evidence distinguishes build completion from runtime acceptance. ## Complete release verification (2026-10-04) For release acceptance and installer/panel regressions, use [the release-validation skill](.codex/skills/tlamatini-release-validation/SKILL.md). A clean-install test requires the authorized installation directory and owned registrations to be removed first. Run the actual compiled Installer.exe with its pkg.zip, then test the installed Admin, Prompt Flow and Agentic Control Panels. Explicit-argument registry tests do not certify the installer’s PowerShell -File invocation. Keep source/frozen and partial/full results distinct.