howaboua-pi-stuff: Instructions file for Codex

Merges to main feed Changesets versioning and npm publishing.

Every package must work against released upstream Pi. Never make monorepo functionality depend on modifying, patching or forking upstream Pi; use supported extension APIs and report unavailable capabilities honestly.

We use this toolkit. If tools fail or cause friction, propose concrete fixes. Apply tiny, low-risk fixes without derailing the task. Edit owning source, never installed tooling. Validate and report changes. Source edits do not update running packages. Sandbox validation means interacting with Pi's TUI through Herdr: normal consecutive turns that execute tools and use the guest environment. Programmatic probes do not require a sandbox and do not substitute for this interaction. For live TUI review, use bun run sandbox:setup --name NAME --live-model openai-codex/MODEL after candidate changes. Reuse the host login through this setup's scoped access-token sync; a functioning authenticated guest is the baseline. Stop active review agents before replacing the guest snapshot; host edits alone never update it. Fix guest readiness instead of moving TUI acceptance onto the host. Release acceptance must run the candidate's bundled native helpers without overrides. Verify guest compatibility first and replace incompatible disposable guests rather than rebuilding helpers around them. Resolve package names against immediate packages subdirectories. Search the unique word match first, then follow direct references. Keep pi-codex-web-run and pi-codex-imagegen src/codex-runtime trees identical. Do not publish a shared runtime package.

Agent-facing text is behaviour. Keep contracts, skills, prompt metadata and subagent prompts compact. Default to general-purpose assistance. Scope coding assumptions to coding tasks. Hide extension internals from agent-facing text, including errors. State what happened, what remains available and an actionable next step. Users own account and configuration decisions. Success may expose a new action, not invented workflow advice. Keep the static prefix small and stable. Defer nonessential tools through Code/Notebook while preserving discovery. Deliver tool guidance on demand through supported mid-session messages or results, not prefix edits. Tool activation changes the live catalogue and chronological notices, not the standing system prompt. Rebuild tool-derived standing instructions from current state only at session/window rollover. Mid-session harness updates use chronological developer messages where supported, Pi custom messages otherwise. Custom messages (pi.sendMessage, customType, display) are extension-labelled UI/history entries converted to provider user messages; purple-box styling does not make them system-role messages. Never substitute Pi system updates: its unsupported-provider fallback folds them into the initial prompt and breaks prefix stability. Extend existing tools, not overlapping choices. Help-backed tools default to no-argument discovery, {} in structured mode. Keep explicit help visible and disclose current arguments on demand. Preserve familiar contracts. Omit obvious field descriptions. Do not repeat obvious contracts across names, descriptions, schemas, promptSnippet and promptGuidelines. Use the latter two only for concrete failures. Never rewrite prior tool calls or results to integrate a tool. Measure emitted tool schemas and system-prompt deltas for cache impact. Repository AGENTS.md is internal guidance, not product prompt cost. Prefer semantic signal over grammatical polish. Drop cosmetic punctuation only if syntax, delimiters, meaning, evidence, caveats and recovery survive. GPT-mode prose uses checkpoint-style fragments, arrows and terse clauses. Measure tokens: keep spaces when joined words cost more; compression must not increase tokens. Preserve syntax, caveats, recovery and normal-mode prose. Skills and extensions must work for any user. Never ship personal names, local paths, machine assumptions or private workflows.