repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

docs(system): initialize project governance

fc56d93a3b83e26352728022cb4002811b8fa521

Oliver Krylow <o.krylow@isp-insoft.de> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (9)

.system/MISSION.md

Added
new file mode 100644
1 +# MISSION
3 +Maintain a personal Pi extension pack that adapts Pi to the maintainer's workflows through small tools, integrations, interface components, and automation.

.system/RULES.md

Added
new file mode 100644
1 +# RULES
3 +## Automation law
5 +- Use Mise as the only public automation interface.
6 +- Treat `mise.toml` files as the source of truth for tools, tasks, dependencies, and orchestration.
7 +- Use an existing Mise task instead of invoking its npm script, Node script, formatter, test runner, or browser runner directly.
8 +- Keep root npm scripts as task implementation details.
9 +- Do not add extension package scripts.
10 +- Add missing automation to the appropriate `mise.toml`.
11 +- Stop and report the exact failure when Mise or its project configuration blocks progress.
13 +## Task discovery
15 +- Run `mise tasks --all` to list root and extension-local tasks.
16 +- Address root tasks as `//:<task>` and extension tasks as `//extensions/<name>:<task>`.
17 +- Use `mise task info <task>` for details, `mise tasks deps <task>` for dependency edges, and `mise run --dry-run <task>` to inspect execution.
18 +- Run `mise tasks validate` after changing root Mise configuration.
19 +- Run `mise -C extensions/<name> tasks validate` after changing extension-local Mise configuration.
21 +## Task selection
23 +- Use `mise run //:install` to install exact locked dependencies.
24 +- Use `mise run //:lock` to regenerate the lockfile.
25 +- Use `mise run //:fmt` to format the repository.
26 +- Use `mise run //:lint` to verify repository formatting and lint.
27 +- Use `mise run //:test` to run the complete test suite once.
28 +- Use `mise run //extensions/<name>:test` to test one extension.
29 +- Use `mise run //extensions/<name>:lint` to lint one extension.
30 +- Use `mise run //extensions/<name>:check` to check one extension.
31 +- Use `mise run //:check` to check all extensions once.
32 +- Use `mise run //:bench` to run all extension benchmarks sequentially.
33 +- Use `mise run //:e2e` to run all browser acceptance suites.
34 +- Use `mise run //:ci` only for the complete release gate.
35 +- Use the root `list`, `changelog`, `readme`, `release-plan`, `release-prepare`, and `publish` tasks for repository operations.
37 +## Efficient execution
39 +- Choose the smallest task that proves the change.
40 +- During iteration, use the affected extension's local `lint`, `test`, or `check` task.
41 +- Stop after the smallest affected tasks pass.
42 +- Run `//:ci`, `//:e2e`, or unrelated suites only when the human explicitly requests that exact wider gate.
43 +- Do not treat commits, merges, or generic verification requests as requests for wider gates.
44 +- For complete tests, run root `//:test` once instead of expanding every extension test wrapper.
45 +- For complete static validation, run root `//:check` once instead of expanding every extension check wrapper.
46 +- Set Mise job counts deliberately when tasks invoke tools that manage their own workers.
47 +- Use `:::` only for independent ad hoc tasks that should run concurrently.
49 +## Task authoring
51 +- Use task dependencies for prerequisites so Mise can deduplicate and schedule shared work.
52 +- Prefer structured task references over command strings that spawn nested Mise processes.
53 +- Treat a task `run` array as sequential execution.
54 +- Use a structured task group for an explicitly parallel stage.
55 +- Spawn nested Mise only when a required scheduler option has no structured-task equivalent.
56 +- Do not enable raw task mode unless the task requires standard input.
58 +## Repository safety
60 +- Preserve unrelated dirty work.
61 +- Do not delete noisy research, cache, or untracked files unless explicitly requested.
62 +- Never print decrypted secrets.
63 +- Never run privileged, root, or elevated commands.
65 +## CI
67 +- Keep repository CI definitions under `.ci/*.kdl` for Luci discovery.
68 +- Delegate CI execution to `CI=true mise run //:ci` instead of duplicating repository gates in Luci configuration.
69 +- Full CI runs on Luci after pushing.
70 +- Run full CI locally only when explicitly requested.
72 +## Git hooks
74 +- Keep pre-commit limited to `check` and `lint`.
75 +- Keep pre-push limited to `check` and `lint`.
76 +- Manage hooks through `mise generate git-pre-commit`.
77 +- Reinstall pre-commit with `mise generate git-pre-commit --write`.
78 +- Reinstall pre-push with `mise generate git-pre-commit --hook pre-push --task pre-push --write`.
80 +## Markdown
82 +- Write one sentence per line.
83 +- Preserve semantic line breaks.
84 +- Let rumdl handle Markdown structure instead of manually reflowing prose.
86 +## Troubleshooting
88 +- Run `mise doctor` when a task fails because a command is unavailable.
89 +- Treat missing activation, missing shims, and mismatched tool binary names as the common first checks.

.system/SYSTEM.md

Added
new file mode 100644
1 +# SYSTEM
3 +## Identity
5 +`pi-ext` is a personal TypeScript and ES-module monorepo of Pi extensions.
6 +Extension workspaces live under `extensions/*`.
8 +## Runtime package
10 +The repository root is the supported Pi installation and distribution unit.
11 +Its manifest exports `extensions/*/index.ts` and no root skills, prompts, or themes.
12 +Package filters may select a subset of those exported resources.
13 +Pi loads the TypeScript extension entrypoints directly through its extension loader.
15 +Extension manifests define private npm workspaces and development boundaries, not independent release units.
16 +Static validation forbids dependencies and imports between sibling extensions.
17 +Workspace dependencies are installed centrally and resolved from the shared installation.
19 +## Automation and verification
21 +Mise exposes the public repository automation interface.
22 +npm owns the workspace dependency graph and lockfile.
23 +Vitest runs source tests, and Playwright runs browser acceptance tests.
24 +Luci runs the repository CI task after pushes.
26 +## Release
28 +The root package owns one repository version and releases use `vX.Y.Z` tags.
29 +Per-extension versions are absent.
30 +Release automation updates documentation, commits, tags, and pushes the source package.
31 +The current release path does not build standalone extension packages or publish to npm.

.system/board.json

Added
new file mode 100644
1 +{
2 + "schemaVersion": 0,
3 + "items": {}
4 +}

.system/config.json

Added
new file mode 100644
1 +{
2 + "prefix": "PX",
3 + "schemaVersion": 0,
4 + "title": "pi-ext"
5 +}

.system/specs/PX-SPEC-DZLVGRW4-pi-extension-architecture/index.md

Added
new file mode 100644
1 +---
2 +id: PX-SPEC-DZLVGRW4
3 +type: spec
4 +title: Pi Extension Architecture
5 +---
7 +## Intent
9 +Make each Pi extension independently developable, testable, installable, releasable, and upgradable without sacrificing fast local work or complete collection use.
10 +Keep runtime behavior close to Pi's Node execution model and reduce startup and reload work through built artifacts.
12 +## Source and package boundaries
14 +The repository root is a development workspace, not a Pi package.
15 +Each extension owns its source, metadata, tests, runtime resources, and generated package.
16 +Extensions neither import sibling extensions nor depend on sibling output paths.
17 +Shared development tooling is allowed; shared runtime files outside an extension package are not.
19 +Every extension emits a complete package under `dist/<extension>`.
20 +Pi settings list each generated extension package explicitly.
21 +The same package boundary is used for local development, verification, npm distribution, and Git distribution.
23 +Extension and shipped runtime code is authored in TypeScript.
24 +Generated JavaScript is allowed.
25 +Bootstrap automation may remain JavaScript when TypeScript would introduce a build-before-build cycle.
27 +## Runtime dependencies
29 +A generated package runs without repository source, workspace links, ancestor `node_modules`, or undeclared ambient files.
30 +Node built-ins, Pi-provided modules, TypeBox modules supplied by Pi, and explicitly declared system executables may remain external.
31 +Portable third-party JavaScript is bundled by default.
32 +An external runtime dependency requires demonstrated bundling incompatibility or a clearly superior explicit integration.
34 +Workers, browser code, templates, filters, executable helpers, and other runtime assets remain inside their owning package.
35 +Pi extensions, skills, prompts, and themes are exposed only when explicitly declared.
36 +Generated manifests map declared resources to generated paths and never expose internal guidance accidentally.
38 +Packages preserve intentional lazy-loading boundaries through package-private generated chunks where useful.
39 +Package loading must not depend on removing or replacing Pi's jiti importer.
41 +## Build behavior
43 +On-demand builds are the primary development interface.
44 +A watcher may invoke the same development build but has no protocol with Pi.
45 +After a successful build, the developer invokes Pi reload explicitly.
47 +Development and release builds emit to the same canonical package directory and intentionally replace one another.
48 +They preserve the same module boundaries, dependency policy, manifest shape, resources, and observable behavior.
49 +They may differ only in debugging information and behavior-neutral optimization.
51 +A failed or interrupted build leaves the last complete package usable.
52 +A successful build publishes the new entrypoint only after its required chunks and resources are complete.
53 +Content-addressed chunks may coexist temporarily so an already loaded extension can finish lazy imports during replacement.
55 +Release verification snapshots the exact generated bytes.
56 +Publication uses that verified snapshot or rejects a digest mismatch.
58 +## Tool ownership
60 +Mise is the stable public automation API and a thin delegation layer.
61 +Mise manages runtimes and tools that the JavaScript package system does not own.
62 +It does not contain the extension build system.
64 +npm owns dependency installation, workspaces, the lockfile, and JavaScript task delegation.
65 +Rolldown owns extension bundling and is a direct development dependency.
66 +Vitest runs source tests on Node.
67 +Playwright owns browser acceptance.
68 +Pi on Node owns generated-package and compatibility verification.
69 +Bun is not part of the toolchain.
71 +Root package scripts and tooling own repository automation.
72 +Extension package scripts remain absent.
74 +## Test architecture
76 +Tests are separated by the guarantee they provide.
78 +Unit and component tests exercise pure source behavior with deterministic inputs and no real Pi session unless necessary.
79 +Property tests belong to this layer and use reproducible seeds, shrinking, and retained regression cases.
80 +Small inline snapshots and readable file snapshots may protect stable rendered output after volatile data is normalized.
82 +Pi contract tests load extension entrypoints through Pi's real loader and exercise registration, lifecycle, dispatch, and provider routing through public APIs.
83 +Every extension has a path-loaded contract and fails on unexpected extension errors.
85 +Native integration tests exercise Node, filesystem, subprocess, Git, HTTP, cancellation, and platform behavior using owned temporary resources and controlled real processes.
86 +Tests requiring distinct process environments run in distinct processes.
88 +Generated-package tests execute immutable package snapshots outside the checkout with independently installed Pi versions.
89 +They verify relocation, manifests, resources, lazy first use, workers, allowed externals, and absence of workspace dependency leakage.
90 +Each extension is tested independently, and the complete configured collection is tested for composition conflicts.
92 +UI acceptance tests exercise generated browser or terminal artifacts through the real UI runner.
94 +## Test fixture constraints
96 +The shared Pi fixture uses public, strongly typed Pi APIs and deterministic scripted providers.
97 +It owns environment, temporary paths, sockets, processes, timers, shutdown, and cleanup explicitly.
98 +Unexpected asynchronous and extension errors fail the test.
99 +Concurrent sessions never pretend to own distinct environments inside one process.
101 +Test correctness does not depend on text-patching installed dependencies or private Pi properties.
102 +An upstream harness is acceptable only when it satisfies the same contract; otherwise the repository owns the narrow fixture it needs.
104 +All maintained TypeScript is checked, including runtime code, tests, fixtures, configuration, workers, browser entrypoints, and TypeScript automation.
105 +Focused checking covers one extension and shared inputs without repeating repository-wide checking.
106 +Root checking covers the union once.
108 +## Verification cadence
110 +Commit hooks contain only quick, deterministic, network-independent checks over the changed scope.
111 +Push hooks may add complete static checking and deterministic source tests.
112 +Hooks exclude browser installation, compatibility matrices, package publication, coverage instrumentation, mutation campaigns, and fuzz campaigns.
114 +Normal CI runs complete static checks, one coordinated source-test run, release builds, current-Pi package verification, and applicable native and UI integration.
115 +Release verification runs the immutable artifacts across the declared Pi, Node, and operating-system matrix.
116 +Current configured Pi compatibility is mandatory.
117 +The minimum supported Pi version is established empirically from an initially broad matrix.
119 +## Test-quality techniques
121 +Coverage reports include unimported owned production files and report line, branch, and function coverage per extension.
122 +Coverage guides investigation and is not initially a percentage gate.
123 +The V8 and Istanbul providers are selected by measured suite behavior.
125 +Property testing is preferred for parsers, normalization, path safety, bounded rendering, serialization, and state machines.
126 +Failures record replay information and yield permanent minimal regression cases.
128 +Mutation testing is selective, incremental, and author-driven while test context is fresh.
129 +It targets pure unit-testable code by file or line range, retains a correctly invalidated per-extension cache, and is not a commit, push, or CI gate.
130 +Occasional full mutation runs may report repository health without imposing a score target.
132 +Snapshot testing protects concise, reviewable output contracts and never replaces semantic assertions.
133 +Snapshots exclude volatile paths, timestamps, identifiers, dependency diagnostics, and generated bundles.
134 +Snapshot updates are explicit and reviewed.
136 +Coverage-guided fuzzing is reserved for narrow hostile-input or security boundaries where property testing is insufficient.
137 +Long fuzz campaigns run manually or on a schedule.
138 +Minimized corpus findings become normal deterministic regression tests.
140 +## Distribution and compatibility
142 +Public distribution uses Pi's normal npm and Git package channels.
143 +Consumers receive built packages and never need the source workspace or build toolchain.
144 +Generated packages contain no lifecycle installation scripts.
146 +Extensions remain independently releasable.
147 +Publication eligibility is independent from local loading, and releases publish only explicitly selected extensions.
148 +Versioning and compatibility metadata have one authoritative source and generated manifests do not become a second source of truth.
150 +The architecture supports Windows, macOS, and Linux.
151 +Platform tools are detected through normal extension behavior and unsupported optional capabilities degrade explicitly.
153 +## Acceptance criteria
155 +- The repository root is not discoverable as a Pi package.
156 +- Pi loads the configured collection from one explicit local package entry per extension.
157 +- A focused development build updates only the selected extension package and leaves a complete reloadable result.
158 +- A release build overwrites the same package location without changing observable behavior.
159 +- Every generated package loads independently outside the checkout with zero unexpected diagnostics.
160 +- No generated package resolves sibling output, repository source, workspace links, or ancestor dependencies.
161 +- Declared resources and lazy first-use paths work after relocation.
162 +- The complete generated collection loads without identity, tool, command, flag, or resource conflicts.
163 +- Current configured Pi passes generated-package verification.
164 +- Compatibility results identify an explicit minimum supported Pi version before public release.
165 +- Focused tests and checking avoid unrelated extension work.
166 +- Root tests use one Vitest coordinator while retaining required worker and process isolation.
167 +- Maintained TypeScript is completely typechecked.
168 +- Release publication consumes the exact verified artifact bytes.
169 +- npm and Git consumers can install selected extensions without compiling source.

AGENTS.md

Deleted
deleted file mode 100644
1 -# Pi Extensions Workspace
3 -Monorepo for Pi extensions under `extensions/*`.
5 -## Automation law
7 -- Mise is the only public automation interface.
8 -- `mise.toml` files are the source of truth for tools, tasks, dependencies, and orchestration.
9 -- Use an existing Mise task instead of invoking its npm script, Node script, formatter, test runner, or browser runner directly.
10 -- Root npm scripts are task implementation details.
11 -- Extension package scripts are prohibited.
12 -- Add missing automation to the appropriate `mise.toml`; do not create ad hoc scripts or bypass Mise.
13 -- If Mise or its project config blocks progress, report the exact failure and stop rather than working around it.
15 -## Task discovery
17 -Run `mise tasks --all` to list tasks.
18 -Use monorepo-root task addresses: `//:<task>` or `//extensions/<name>:<task>`.
19 -Use extension-local tasks for one extension; root tasks for repository-wide checks.
20 -Before selecting unfamiliar tasks, editing Mise configuration, or managing hooks, read [docs/automation.md](docs/automation.md).
22 -## Efficient execution
24 -Choose the smallest task that proves the change.
26 -- During iteration, use one extension's local `lint`, `test`, or `check` task.
27 -- Agents stop after the smallest affected tasks pass.
28 -- Agents run `//:ci`, `//:e2e`, or unrelated suites only when the user explicitly requests that exact wider gate.
29 -- Commits, merges, and generic verification requests do not imply wider gates.
30 -- For explicitly requested complete tests, run root `//:test` once; do not fan out all extension `test` wrappers into one Vitest process per extension.
31 -- For explicitly requested complete static validation, run root `//:check` once; do not fan out all extension `check` wrappers because each repeats repository-wide TypeScript checking.
33 -Mise task jobs and tool workers multiply.
34 -Set `--jobs` deliberately when invoking multiple independent tasks, because Vitest, Playwright, and other tools manage their own workers.
35 -Use `:::` only for independent ad hoc tasks that should run concurrently.
37 -## CI hosting
39 -Luci at `ci.bugabinga.net` auto-discovers `.ci/*.kdl` from the public Soft Serve repository.
40 -Repository CI must delegate to `CI=true mise run //:ci`; do not duplicate gates in Luci configuration.
42 -Full CI runs on Luci after pushing.
43 -Run `mise run //:ci` locally only when the user explicitly requests it.
45 -## Extension engineering
47 -- Nested model calls must use `ctx.modelRegistry`, never pi-ai compatibility dispatchers, so extension-registered providers work.
49 -### Startup performance
51 -- Treat every Win32 process spawn as expensive.
52 -- Prefer native Node APIs and defer unavoidable spawns until first use.
53 -- Keep entry modules thin and lazy-load command or tool implementations.
54 -- Gate optional domain work with cheap relevance checks before imports.
55 -- Never block startup or reload on subprocess probes, broad filesystem scans, or Git status.
56 -- Abort asynchronous startup work on reload and ignore stale results.
57 -- Check executable presence through native `PATH` access, not version subprocesses.
58 -- Preserve registration, validation, rendering, and first-use behavior when deferring work.
59 -- Measure performance with the complete extension set on Win32 and WSL.
61 -### Tool widget rendering
63 -Tool widgets must match Pi built-ins: compact by default, expanded details on `app.tools.expand` (`ctrl+o` by default).
64 -Normal tool rows must rely on Pi-owned keyboard and mouse expansion; do not register extension shortcuts or mouse handlers for them.
65 -Every custom `renderCall` and `renderResult` must honor native expanded state, including progress, errors, and malformed-detail fallback paths.
66 -Collapsed `renderResult` output may show status, counts, paths, IDs, and tiny bounded summaries only.
67 -Full content, previews, snippets, verbose logs, structured bodies, and per-result lists require `expanded === true`.
68 -When content is hidden, show `keyHint("app.tools.expand", "to expand")`; do not use legacy `expandTools`.
69 -Focused custom overlays and non-tool widgets may handle their own expansion action because they do not inherit normal tool-row input handling.
71 -### Cross-platform requirements
73 -All extensions must work on Windows, macOS, and Linux.
74 -Do not add OS-scoped extensions.
75 -Do not rely on shell helpers such as `which`, `bash`, `sed`, `grep`, or `/tmp` when Node APIs can do the job.
76 -If an extension uses platform tools, check availability when the extension loads.
77 -Notify missing required tools with warning severity and missing optional tools with info severity.
78 -Tests for platform-tool behavior must exercise the real extension or tool path with controlled fake binaries on `PATH`, not only mocked helpers.
80 -## Markdown style
82 -Use one sentence per line for prose.
83 -Keep semantic line breaks unless rewording the sentence.
84 -Let `rumdl` handle Markdown structure; do not manually reflow paragraphs for visual width.
86 -## Git hooks
88 -- `pre-commit` runs check and lint.
89 -- `pre-push` runs check and lint.
90 -- Luci runs full CI.
92 -## Troubleshooting
94 -Run `mise doctor` when a task fails because a command is unavailable.
95 -Common causes are missing activation, missing shims, or a mismatched tool binary name.

docs/automation.md

Deleted
deleted file mode 100644
1 -# Automation guide
3 -Task selection, task authoring, and Git hook setup for `pi-ext`.
4 -The always-loaded rules remain in [AGENTS.md](../AGENTS.md).
6 -## Task discovery
8 -Run `mise tasks --all` to list root and extension-local tasks.
9 -Use monorepo-root paths when referring to tasks from automation or documentation:
11 -- `//:test` addresses a root task.
12 -- `//extensions/angel:test` addresses an extension task.
13 -- `//extensions/...:bench` selects a task across matching extension config roots.
15 -Task-name groups and wildcards select tasks; they do not create dependencies or ordering.
16 -Use `mise task info <task>` for task details, `mise tasks deps <task>` for declared dependency edges, and `mise run --dry-run <task>` to inspect execution.
17 -Run `mise tasks validate` after changing the root config.
18 -Run `mise -C extensions/<name> tasks validate` after changing an extension config.
20 -## Choosing tasks
22 -| Need | Command |
23 -| --- | --- |
24 -| Install exact locked dependencies | `mise run //:install` |
25 -| Regenerate `package-lock.json` | `mise run //:lock` |
26 -| Format the repository | `mise run //:fmt` |
27 -| Verify repository formatting and lint | `mise run //:lint` |
28 -| Run the complete test suite once | `mise run //:test` |
29 -| Run one extension's tests | `mise run //extensions/<name>:test` |
30 -| Lint one extension | `mise run //extensions/<name>:lint` |
31 -| Typecheck and statically check one extension | `mise run //extensions/<name>:check` |
32 -| Typecheck and statically check all extensions | `mise run //:check` |
33 -| Run all benchmarks sequentially | `mise run //:bench` |
34 -| Run all browser E2E suites | `mise run //:e2e` |
35 -| Run the release gate | `mise run //:ci` |
37 -Use `mise run //:test -- extensions/<name>` and `mise run //:build -- <name>` only when implementing a local task or diagnosing its root delegate.
38 -Normal agent workflows should use the extension-local task names.
40 -Root operation tasks are `//:list`, `//:changelog`, `//:readme`, `//:release-plan`, `//:release-prepare`, and `//:publish`.
41 -Invoke one with `mise run`, passing extension names after `--`, for example `mise run //:readme -- angel`.
43 -## Task authoring
45 -Use `depends` for prerequisites so Mise can deduplicate shared work and schedule independent dependencies concurrently.
46 -Use structured task references instead of spawning nested Mise processes:
48 -```toml
49 -run = [{ task = "//:test", args = ["extensions/angel"] }]
50 -```
52 -A `run` array is sequential.
53 -Use `{ tasks = ["check", "lint"] }` for an explicit parallel stage inside that sequence.
54 -Structured task references execute their own dependencies but do not appear as edges in `mise tasks deps`.
55 -Use a nested `mise run` command only when a required CLI scheduler option, such as `--jobs 1`, has no structured-task equivalent.
57 -Do not set `raw = true` unless a task requires stdin.
58 -Raw tasks serialize against other tasks and disable output redaction.
60 -## Git hook setup
62 -Hooks are managed through `mise generate git-pre-commit`.
63 -Reinstall them with `mise generate git-pre-commit --write`, then `mise generate git-pre-commit --hook pre-push --task pre-push --write`.
64 -The `pre-commit` and `pre-push` tasks in [mise.toml](../mise.toml) define their execution.

extensions/AGENTS.md

Modified
1 1 # Extension Packages
3 3 These rules apply to every package under `extensions/*`.
4 -The workspace automation and execution rules in the root `AGENTS.md` also apply.
6 5 ## New extension checklist
84 83 Optional integration must use capabilities or events and degrade cleanly.
85 84 Important behavior needs a native fallback; decorative integration may no-op.
86 +## Model calls
88 +Nested model calls must use `ctx.modelRegistry`, never Pi AI compatibility dispatchers, so extension-registered providers work.
87 90 ## Imports
89 92 | Package | Provides | Placement |
103 106 ## Startup
105 108 `session_start` must be fast.
109 +Treat every Windows process spawn as expensive.
110 +Prefer native Node APIs and defer unavoidable process spawns until first use.
111 +Keep entry modules thin and lazy-load command or tool implementations.
112 +Gate optional domain work with cheap relevance checks before imports.
106 113 Do not await network access, Git, filesystem scans, or subprocesses during startup.
107 114 Publish minimal UI immediately, then defer slow work with a background task and generation or stale-result guard.
115 +Abort asynchronous startup work on reload and ignore stale results.
116 +Check executable presence through native `PATH` access, not version subprocesses.
108 117 Never block other extensions for telemetry, recovery, decoration, or cache warming.
118 +Preserve registration, validation, rendering, and first-use behavior when deferring work.
119 +Measure startup performance with the complete extension set on Windows and WSL.
121 +## Tool widgets
123 +Tool widgets must match Pi built-ins: compact by default and expanded through `app.tools.expand`.
124 +Normal tool rows must rely on Pi-owned keyboard and mouse expansion.
125 +Every custom `renderCall` and `renderResult` must honor native expanded state, including progress, errors, and malformed-detail fallbacks.
126 +Collapsed results may show status, counts, paths, identifiers, and tiny bounded summaries only.
127 +Full content, previews, snippets, verbose logs, structured bodies, and per-result lists require expanded state.
128 +When content is hidden, show `keyHint("app.tools.expand", "to expand")`.
129 +Do not use the legacy `expandTools` action.
130 +Focused overlays and non-tool widgets may handle their own expansion action.
132 +## Cross-platform behavior
134 +All extensions must work on Windows, macOS, and Linux.
135 +Do not add operating-system-scoped extensions.
136 +Prefer native Node APIs over shell helpers such as `which`, `bash`, `sed`, `grep`, or `/tmp`.
137 +Check platform-tool availability when the extension loads.
138 +Report missing required tools with warning severity and missing optional tools with info severity.
139 +Test platform-tool behavior through the real extension or tool path with controlled fake executables on `PATH`, not only mocked helpers.
110 141 ## Context impact