pi-extensions: Instructions file for Codex

Repository Guidelines

Documentation

• Lead with the most important information and use concise, accurate prose without repetition.
• Use concise paragraphs for human-facing narrative and lists only when separate items are easier to scan.
• Keep AGENTS.md instructions as one-sentence, enforceable bullet points.
• Follow docs/readme-conventions.md for active package READMEs, including its required sections, warnings, scope rules, and verification checklist.
• Keep package versions out of long-lived guidance and derive them from manifests, lockfiles, or workflows.

Code style

• Follow KISS and YAGNI, add dependencies only for current needs, and use Pi core functions when they already provide the required behavior.
• Use NodeNext modules, ES2024, strict TypeScript, and no emit for root TypeScript.
• Upgrade outdated dependencies instead of removing or downgrading valid code to hide their type errors.
• Split source files over 1,000 lines by clear responsibility, but do not mechanically split generated, vendored, migration, snapshot, or mainly declarative files.

Commands and tooling

• Run commands from the repository root unless their documentation says otherwise.
• Use npm install to install dependencies, npm run format to apply Biome formatting, and npm run typecheck to typecheck every workspace.
• Run npm run before adding or documenting a root workflow command.
• Keep root npm scripts as canonical entrypoints only for workflows users run from the root, and move complex implementations under scripts/.
• Keep pre-commit hook logic in scripts/pre-commit.sh, invoke it directly from .husky/pre-commit, and do not add a duplicate root npm script.
• Do not run root checks concurrently with a pi-tui-kit build or check because both clear packages/pi-tui-kit/dist.
• Rebuild pi-tui-kit before consumer tests because consumers resolve its built output.
• After raising a consumer's Kit floor, run root npm install, verify the resolution with npm ls @narumitw/pi-tui-kit, and then typecheck.
• Keep imported Pi packages in root devDependencies so tests emitted under node_modules/.cache resolve the intended versions.
• Prefer Pi AI root exports, and use a variable-specifier dynamic import only when a required subpath has no root export because official Pi can misresolve static @earendil-works/pi-ai/api/* imports.
• Treat Pi's user and project managed npm roots as separate install scopes because deduplication is guaranteed only within one root.
• Never use npm audit fix --force; if it changes Pi dependencies, restore every workspace manifest and the lockfile before applying targeted patched upgrades or overrides.