pine-of-glass: Instructions file for Codex

pine-of-glass: agent notes

Three pi extensions (contextimate, traceline, cachemire) sharing one design language. TypeScript, zero runtime dependencies, tests on node:test.

Commands

npm install             # locked Pi runtime (types, contract tests, smoke) and lint tooling; npm update adopts a new Pi
npm run link-pi         # optional: check against your installed pi instead; npm install undoes it
npm run docs:cache      # regenerate Cachemire retention docs
npm run lint            # POG rules + oxlint/anti-slop (baselined) + generated-doc drift checks
npm run lint:slop       # oxlint alone, full diagnostics
npm run typecheck       # tsc against the locked (or linked) pi
npm test                # unit + golden + pi contract tests (node:test)
npm run check           # lint + typecheck + tests
npm run test:smoke      # launches real pi in tmux with an isolated HOME (local-only)

Layout & rules

• One extension per extensions/pi-<name>/; shared code lives in extensions/_lib: number grammar, family style (glyphs, theme-derived ink, panel headers), ANSI helpers, chat-container detection, config convention. _lib has no index.ts, so pi's extension discovery skips it.
• Install for daily use with pi install git:github.com/tmustier/pine-of-glass. To try a branch, check it out in the installed clone (~/.pi/agent/git/github.com/tmustier/pine-of-glass) and /reload; pi update --extensions returns it to main. Do not also load a checkout with pi -e or symlinks: Pi treats it as a second package and registers every extension twice. Without the git install, pi install <checkout path> runs from a checkout.
• docs/design-language.md specifies the visual grammar all three extensions speak. Record design changes there first, then implement; when a renderer and that document disagree, one of them is wrong.
• The contract suite pins every structural assumption about pi internals, so after pi update, npm run link-pi && npm test says exactly which seam (if any) drifted. Test design notes: docs/testing.md.
• Before changing Cachemire retention, read the dated audit. retention.ts drives runtime resolution and generated policy docs; cacheClock() owns clock wording. Match the exact route, model and outgoing policy. Keep minimum and maximum semantics distinct, and leave unmatched routes unknown. Run npm run docs:cache after policy changes.
• Goldens regenerate with UPDATE_GOLDENS=1 npm test. Review the diff like code. Regenerate whenever rendering changes.
• README screenshots regenerate with the rig in scripts/dev/screenshots/: real pi TUI in an isolated tmux/HOME; see its README for the recipe. The cachemire scenario makes live model calls (costs cents).
• Agent coding standards live in docs/agent-coding-standard.md and are enforced by scripts/dev/agent-lint.mjs and .oxlintrc.json. Parse external data at its boundary, pass typed values inward, and document real escape hatches with SAFETY: comments. The baseline and legacy internals exports only shrink.
• Tests specify capabilities through Pi's SDK or stable domain-module APIs; do not expose private helpers for tests. See docs/testing.md.